Projets/Imago
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix README: correct deploy steps, remove stale alembic/run.py refs, add registry + new docs
CI / Lint & Format (push) Failing after 10s
Details
CI / Tests (push) Has been skipped
Details
CI / Security Scan (push) Failing after 8s
Details
CI / Docker Build (push) Has been skipped
Details

Browse Source
This commit is contained in:
bruno
2026-06-22 20:46:38 -04:00
parent e977b6f2a3
commit 6b7cdcdb62
1 changed files with 78 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+78 -49
View File
@@ -1,85 +1,114 @@
# Imago Hub
# Imago Hub v2.0.0
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
## 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.
- **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 :** Données EXIF, géolocalisation GPS, résolution et caractéristiques des fichiers.
- **Pipelines OCR :** Extraction de texte via Tesseract + fallback IA.
- **Vision IA Intégrée :** Description de scènes et classification par tags (Gemini & OpenRouter) avec circuit breaker.
- **Flux Temps Réel :** Streaming d'événements WebSocket du pipeline (Redis Pub/Sub + buffer 60s).
- **Sécurité & Multi-tenancy :** Auth API Key (SHA-256+pepper, timing-safe), scopes, rate limiting par plan, isolation totale.
- **Portail d'Administration :** Interface React pour gérer les clients, surveiller la file d'attente, consulter les métriques.
- **Dead Letter Queue :** Jobs échoués inspectables et relançables via API admin.
- **SDK Python :** `imago-client` pour intégration programmatique (HTTP + WebSocket).
## 📚 Documentation Complète
## Documentation
Pour une compréhension approfondie du projet, veuillez consulter les documents suivants dans le répertoire `doc/` :
- **[Guide d'Utilisation](docs/USER_GUIDE.md)** — Utilisation des fonctionnalités et portail admin
- **[Architecture](docs/ARCHITECTURE.md)** — Stack technique et flux de données
- **[Guide API](docs/API_GUIDE.md)** — Référence complète des endpoints REST + WebSocket
- **[Guide SDK Python](docs/SDK.md)** — Intégration programmatique
- **[Guide WebSocket](docs/WEBSOCKET.md)** — Streaming temps réel
- **[Guide Intégration Shaarli](docs/SHAARLI-INTEGRATION.md)** — Plugin Shaarli
- **[Roadmap](docs/ROADMAP.md)** — Correctifs, architecture, idées futures (107 fonctionnalités)
- **[Checklist Production](docs/PRODUCTION_CHECKLIST.md)** — 46 points avant la mise en production
- **[Guide Déploiement](docs/DEPLOYMENT.md)** — Déploiement sur serveur Docker
- **[CHANGELOG](CHANGELOG.md)** — Historique des versions
- 📖 **[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.
*La spécification OpenAPI est disponible sur `http://localhost:8000/docs` (application lancée).*
*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).*
## Déploiement rapide (Docker)
## 🚀 Installation via Docker (Recommandé)
Le projet fournit un `docker-compose.yml` complet orchestrant tous les services :
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
| Service | Port | Rôle |
|---|---|---|
| backend | 8000 | API FastAPI |
| admin | 3000 | Portail React + Nginx |
| worker | — | ARQ (pipeline AI asynchrone) |
| db | 5432 | PostgreSQL 16 |
| redis | 6379 | Redis 7 (broker, cache, pub/sub) |
| minio | 9000-9001 | Stockage S3-compatible |
```bash
# 1. Cloner le dépôt
# 1. Cloner
git clone https://git.dracodev.net/Projets/Imago.git
cd imago
# 2. Configuration de l'environnement
# 2. Configurer 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)
# Éditer .env : ajouter GEMINI_API_KEY ou OPENROUTER_API_KEY
# 3. Lancer toute la stack
docker-compose up -d --build
# 3. Démarrer la stack (depuis imago-admin/)
cd imago-admin
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
# 4. Récupérer la clé admin (affichée au premier démarrage)
docker compose logs backend | grep "Bootstrap client created"
```
L'API sera disponible sur [http://localhost:8000](http://localhost:8000) et le panel admin sur [http://localhost:3000](http://localhost:3000).
L'API : http://localhost:8000/docs | Admin : http://localhost:3000
---
> **Note :** La base de données est créée automatiquement au démarrage via `init_db()`. La clé admin est générée et affichée dans les logs au premier lancement.
## 💻 Installation Locale (Développement)
## Déploiement sur serveur (production)
Si vous souhaitez exécuter le projet sans Docker (nécessite Python 3.10+, PostgreSQL ou SQLite, Redis et Tesseract OCR) :
L'image est disponible sur le registry local du lab :
```bash
# 1. Setup Venv
# Sur le serveur cible
mkdir -p /opt/imago && cd /opt/imago
# Copier docker-compose.production.yml et .env.production
docker compose -f docker-compose.production.yml up -d
```
Voir **[Guide Déploiement](docs/DEPLOYMENT.md)** pour la procédure complète.
## Build et push vers le registry
```powershell
cd docker
.\build-img.ps1 # Build via WSL Debian
.\deploy-img.ps1 # Push vers docker-registry.dev.home:5000 (semver auto)
```
## Développement local (sans Docker)
Prérequis : Python 3.12+, Redis, PostgreSQL (ou SQLite), Tesseract OCR.
```bash
# 1. Environnement virtuel
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# 2. Base de données & Migrations
# 2. Configuration
cp .env.example .env
alembic upgrade head
# Éditer .env : DATABASE_URL=sqlite+aiosqlite:///./data/imago.db (pour SQLite local)
# 3. Démarrage
python run.py # API Endpoint -> http://localhost:8000
python worker.py # Required ARQ Redis Jobs
# 3. Démarrer l'API
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
# 4. Démarrer le worker (terminal séparé)
python worker.py
```
## 🧪 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 :
## Tests
```bash
make test
# Ou directement :
pip install -r requirements-dev.txt
pytest tests/ -v
```
Veuillez consulter le `CHANGELOG.md` pour suivre les développements majeurs.
Consulter le **[CHANGELOG](CHANGELOG.md)** pour l'historique des versions.