bruno
2f2a5e9b4a
Introduce an admin portal (React + Nginx), WebSocket routing, and API versioning middleware with `/api/v1/` prefix deprecation. Add master API key authentication, new Prometheus metrics for AI token consumption and active WebSockets, and extend S3 config with a public endpoint URL. Update test paths and fixtures to align with the new routing structure.
86 lines
4.3 KiB
Markdown
86 lines
4.3 KiB
Markdown
# Imago Hub
|
|
|
|
Imago est un hub Backend & Traitement IA multi-tenant open-source dédié à la gestion d'images. Conçu pour propulser des applications frontend riches (comme Shaarli), il offre un stockage média hautement concurrent, des traitements asynchrones planifiés, une observabilité complète du pipeline et des intégrations poussées avec l'Intelligence Artificielle.
|
|
|
|
## ✨ Fonctionnalités Principales
|
|
|
|
- 📸 **API d'Upload & Stockage :** Stockage d'images isolé par client (multi-tenant), génération automatique de miniatures, support S3 (MinIO) ou stockage local.
|
|
- 🔍 **Extraction de Métadonnées :** Découverte en temps réel des données EXIF, géolocalisation GPS, résolution et caractéristiques des fichiers.
|
|
- 📝 **Pipelines OCR :** Extraction de texte hors-ligne intégrée aux images via le moteur Tesseract.
|
|
- 🤖 **Vision IA Intégrée :** Résumé automatique de contenu, description de scènes, et classification par tags (Propulsé par les API Gemini & OpenRouter).
|
|
- ⚡ **Flux de Données en Temps Réel :** Streaming d'événements WebSocket encapsulant les opérations lourdes de la file d'attente (ARQ / Redis).
|
|
- 🔐 **Sécurité & Multi-tenancy :** Authentification par clé API, gestion de quotas (Rate Limiting) basés sur des plans, isolation totale des données entre les clients.
|
|
- 💻 **Portail d'Administration :** Interface React complète pour gérer les clients API, surveiller la file d'attente et consulter les métriques.
|
|
|
|
## 📚 Documentation Complète
|
|
|
|
Pour une compréhension approfondie du projet, veuillez consulter les documents suivants dans le répertoire `doc/` :
|
|
|
|
- 📖 **[Guide d'Utilisateur (USER_GUIDE.md)](doc/USER_GUIDE.md) :** Explications détaillées sur l'utilisation des fonctionnalités, le portail admin et les concepts clés.
|
|
- 🏗️ **[Architecture (ARCHITECTURE.md)](doc/ARCHITECTURE.md) :** Plongée technique dans la stack (FastAPI, React, Redis, ARQ, MinIO) et le fonctionnement du pipeline asynchrone.
|
|
- 📡 **[Guide de l'API (API_GUIDE.md)](doc/API_GUIDE.md) :** Référence complète des endpoints REST, de l'authentification et des exemples de requêtes.
|
|
- 🔌 **[Guide SDK Python](docs/sdk.md) & [WebSockets](docs/websocket.md) :** (Dans le dossier `docs/`) Pour l'intégration programmatique bas-niveau.
|
|
|
|
*Note: La spécification OpenAPI pour l'écosystème `/api/v1/` peut être consultée dynamiquement sur `http://localhost:8000/docs` (une fois l'application lancée).*
|
|
|
|
## 🚀 Installation via Docker (Recommandé)
|
|
|
|
Le projet fournit une configuration `docker-compose.yml` complète qui orchestre tous les services nécessaires :
|
|
1. **admin** : Portail d'administration (React + Nginx) sur le port `3000`
|
|
2. **backend** : API Imago (FastAPI) sur le port `8000`
|
|
3. **db** : Base de données PostgreSQL
|
|
4. **redis** : Serveur Redis (Broker & Cache)
|
|
5. **worker** : Worker ARQ pour les tâches IA & OCR en arrière-plan
|
|
6. **minio** : Serveur de stockage objet compatible S3 sur les ports `9000` (API) et `9001` (Console)
|
|
|
|
### Étapes de déploiement
|
|
|
|
```bash
|
|
# 1. Cloner le dépôt
|
|
git clone <repo_url>
|
|
cd imago
|
|
|
|
# 2. Configuration de l'environnement
|
|
cp .env.example .env
|
|
# (Éditez le fichier .env si nécessaire, notamment pour ajouter vos clés API IA : GEMINI_API_KEY ou OPENROUTER_API_KEY)
|
|
|
|
# 3. Lancer toute la stack
|
|
docker-compose up -d --build
|
|
|
|
# 4. Appliquer les migrations de base de données (si non faites automatiquement)
|
|
docker-compose exec backend alembic upgrade head
|
|
```
|
|
|
|
L'API sera disponible sur [http://localhost:8000](http://localhost:8000) et le panel admin sur [http://localhost:3000](http://localhost:3000).
|
|
|
|
---
|
|
|
|
## 💻 Installation Locale (Développement)
|
|
|
|
Si vous souhaitez exécuter le projet sans Docker (nécessite Python 3.10+, PostgreSQL ou SQLite, Redis et Tesseract OCR) :
|
|
|
|
```bash
|
|
# 1. Setup Venv
|
|
pip install -r requirements.txt
|
|
|
|
# 2. Base de données & Migrations
|
|
cp .env.example .env
|
|
alembic upgrade head
|
|
|
|
# 3. Démarrage
|
|
python run.py # API Endpoint -> http://localhost:8000
|
|
python worker.py # Required ARQ Redis Jobs
|
|
```
|
|
|
|
## 🧪 Tests
|
|
|
|
Nous exécutons une suite de tests automatisée résiliente (80+ tests) simulant nativement des buckets S3 et l'infrastructure ARQ sans dépendance réseau externe :
|
|
|
|
```bash
|
|
make test
|
|
# Ou directement :
|
|
pytest tests/ -v
|
|
```
|
|
|
|
Veuillez consulter le `CHANGELOG.md` pour suivre les développements majeurs.
|