docs: mise à jour README avec nouvelle structure et scripts

2026-06-23 22:19:51 -04:00
parent a626ab4981
commit eeddca1794
1 changed files with 101 additions and 87 deletions
@@ -1,107 +1,110 @@
 # 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.
+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, 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

- **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).
+| Catégorie | Détails |
+|---|---|
+| **Upload & Stockage** | Multi-tenant, miniatures auto, stockage local ou S3 (MinIO/AWS/Cloudflare R2) |
+| **Métadonnées** | EXIF, GPS, résolution |
+| **OCR** | Tesseract + fallback IA |
+| **Vision IA** | Description de scènes + tags (OpenRouter / Gemini) |
+| **Temps réel** | WebSocket via Redis Pub/Sub |
+| **Sécurité** | API Key SHA-256+pepper, scopes, rate limiting par plan |
+| **Admin Panel** | Interface React : clients, galerie, métriques, logs |
+| **SDK Python** | `imago-client` pour intégration programmatique |

-## Documentation
+## Structure du projet

- **[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
-
-*La spécification OpenAPI est disponible sur `http://localhost:8000/docs` (application lancée).*
-
-## Déploiement rapide (Docker)
-
-Le projet fournit un `docker-compose.yml` complet orchestrant tous les services :
-
-| 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
-git clone https://git.dracodev.net/Projets/Imago.git
-cd Imago
-
-# 2. Configurer l'environnement
-cp .env.example .env
-# Éditer .env : ajouter GEMINI_API_KEY ou OPENROUTER_API_KEY
-
-# 3. Démarrer la stack (depuis imago-admin/)
-cd imago-admin
-docker compose up -d --build
-
-# 4. Récupérer la clé admin (affichée au premier démarrage)
-docker compose logs backend | grep "Bootstrap client created"
+```
+imago/
+├── docker-compose/                # Fichiers Docker Compose
+│   ├── docker-compose.yml         # Développement local (build + S3)
+│   ├── docker-compose.prod.yml    # Production (images pré-buildées)
+│   └── .env.example               # Template de configuration
+├── scripts/
+│   ├── setup.sh                   # Préparation unique du serveur
+│   └── deploy.sh                  # Déploiement / mise à jour
+├── app/                           # Code backend FastAPI
+├── imago-admin/                   # Frontend admin React
+├── sdk/                           # SDK Python
+└── docs/                          # Documentation
 ```

-L'API : http://localhost:8000/docs | Admin : http://localhost:3000
+## Déploiement rapide

-> **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.
-
-## Déploiement sur serveur (production)
-
-L'image est disponible sur le registry local du lab :
+### Sur un nouveau serveur (2 commandes)

 ```bash
-# Sur le serveur cible
-mkdir -p /DOCKER_CONFIG/Imago && cd /DOCKER_CONFIG/Imago
-# Copier docker-compose.production.yml et .env.production
-docker compose -f docker-compose.production.yml up -d
+git clone https://git.dracodev.net/Projets/Imago.git /opt/imago
+cd /opt/imago
+
+# 1. Préparer le serveur (une seule fois)
+sudo ./scripts/setup.sh
+
+# Déconnectez/reconnectez-vous (groupe docker)
 ```

-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
+# 2. Déployer
+cd /opt/imago
+./scripts/deploy.sh
+```
+
+Le script interactif vous guidera : création du `.env`, saisie des clés API, démarrage des services. Au premier lancement, la clé admin bootstrap s'affiche.
+
+### Commandes au quotidien
+
+```bash
+./scripts/deploy.sh -u     # Mise à jour (pull + recréation)
+./scripts/deploy.sh -s     # État des conteneurs
+./scripts/deploy.sh -l     # Logs en temps réel
+```
+
+### URLs d'accès
+
+| Service | URL |
+|---|---|
+| Admin UI | `http://<serveur>:3001` |
+| API Docs | `http://<serveur>:8001/docs` |
+| Health | `http://<serveur>:8001/health` |
+
+## Développement local
+
+```bash
+# Stack Docker complète (build from source)
+docker compose -f docker-compose/docker-compose.yml up -d --build
+
+# Récupérer la clé admin
+docker compose -f docker-compose/docker-compose.yml logs backend | grep "Bootstrap client"
+```
+
+```bash
+# Sans Docker
 python3 -m venv .venv && source .venv/bin/activate
 pip install -r requirements.txt
-
-# 2. Configuration
-cp .env.example .env
-# Éditer .env : DATABASE_URL=sqlite+aiosqlite:///./data/imago.db (pour SQLite local)
-
-# 3. Démarrer l'API
+cp .env.example .env  # Configurer DATABASE_URL, clés AI
 uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+python worker.py      # Terminal séparé
+```

-# 4. Démarrer le worker (terminal séparé)
-python worker.py
+## Build des images
+
+```powershell
+# Depuis Windows (WSL Debian requis)
+
+# Backend
+cd C:\dev\git\python\imago
+docker build --no-cache -t docker-registry.dev.home:5000/imago-backend:latest -f Dockerfile .
+
+# Admin
+cd imago-admin
+docker build --no-cache -t docker-registry.dev.home:5000/imago-admin:latest .
+
+# Push
+docker push docker-registry.dev.home:5000/imago-backend:latest
+docker push docker-registry.dev.home:5000/imago-admin:latest
 ```

 ## Tests
@@ -111,4 +114,15 @@ pip install -r requirements-dev.txt
 pytest tests/ -v
 ```

-Consulter le **[CHANGELOG](CHANGELOG.md)** pour l'historique des versions.
+## Documentation
+
+- **[Guide d'Utilisation](docs/USER_GUIDE.md)** — Utilisation et portail admin
+- **[Architecture](docs/ARCHITECTURE.md)** — Stack technique et flux
+- **[Guide API](docs/API_GUIDE.md)** — Endpoints REST + WebSocket
+- **[Guide SDK Python](docs/SDK.md)** — Intégration programmatique
+- **[Guide Déploiement](docs/DEPLOYMENT.md)** — Procédure détaillée
+- **[Roadmap](docs/ROADMAP.md)** — 107 fonctionnalités planifiées
+- **[Checklist Production](docs/PRODUCTION_CHECKLIST.md)** — 46 points avant prod
+- **[CHANGELOG](CHANGELOG.md)** — Historique des versions
+
+*Spécification OpenAPI : `http://<serveur>:8001/docs`*