docs: mise à jour README avec nouvelle structure et scripts
This commit is contained in:
@@ -1,107 +1,110 @@
|
|||||||
# Imago Hub v2.0.0
|
# 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.
|
| Catégorie | Détails |
|
||||||
- **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.
|
| **Upload & Stockage** | Multi-tenant, miniatures auto, stockage local ou S3 (MinIO/AWS/Cloudflare R2) |
|
||||||
- **Vision IA Intégrée :** Description de scènes et classification par tags (Gemini & OpenRouter) avec circuit breaker.
|
| **Métadonnées** | EXIF, GPS, résolution |
|
||||||
- **Flux Temps Réel :** Streaming d'événements WebSocket du pipeline (Redis Pub/Sub + buffer 60s).
|
| **OCR** | Tesseract + fallback IA |
|
||||||
- **Sécurité & Multi-tenancy :** Auth API Key (SHA-256+pepper, timing-safe), scopes, rate limiting par plan, isolation totale.
|
| **Vision IA** | Description de scènes + tags (OpenRouter / Gemini) |
|
||||||
- **Portail d'Administration :** Interface React pour gérer les clients, surveiller la file d'attente, consulter les métriques.
|
| **Temps réel** | WebSocket via Redis Pub/Sub |
|
||||||
- **Dead Letter Queue :** Jobs échoués inspectables et relançables via API admin.
|
| **Sécurité** | API Key SHA-256+pepper, scopes, rate limiting par plan |
|
||||||
- **SDK Python :** `imago-client` pour intégration programmatique (HTTP + WebSocket).
|
| **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
|
imago/
|
||||||
- **[Guide API](docs/API_GUIDE.md)** — Référence complète des endpoints REST + WebSocket
|
├── docker-compose/ # Fichiers Docker Compose
|
||||||
- **[Guide SDK Python](docs/SDK.md)** — Intégration programmatique
|
│ ├── docker-compose.yml # Développement local (build + S3)
|
||||||
- **[Guide WebSocket](docs/WEBSOCKET.md)** — Streaming temps réel
|
│ ├── docker-compose.prod.yml # Production (images pré-buildées)
|
||||||
- **[Guide Intégration Shaarli](docs/SHAARLI-INTEGRATION.md)** — Plugin Shaarli
|
│ └── .env.example # Template de configuration
|
||||||
- **[Roadmap](docs/ROADMAP.md)** — Correctifs, architecture, idées futures (107 fonctionnalités)
|
├── scripts/
|
||||||
- **[Checklist Production](docs/PRODUCTION_CHECKLIST.md)** — 46 points avant la mise en production
|
│ ├── setup.sh # Préparation unique du serveur
|
||||||
- **[Guide Déploiement](docs/DEPLOYMENT.md)** — Déploiement sur serveur Docker
|
│ └── deploy.sh # Déploiement / mise à jour
|
||||||
- **[CHANGELOG](CHANGELOG.md)** — Historique des versions
|
├── app/ # Code backend FastAPI
|
||||||
|
├── imago-admin/ # Frontend admin React
|
||||||
*La spécification OpenAPI est disponible sur `http://localhost:8000/docs` (application lancée).*
|
├── sdk/ # SDK Python
|
||||||
|
└── docs/ # Documentation
|
||||||
## 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"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
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.
|
### Sur un nouveau serveur (2 commandes)
|
||||||
|
|
||||||
## Déploiement sur serveur (production)
|
|
||||||
|
|
||||||
L'image est disponible sur le registry local du lab :
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Sur le serveur cible
|
git clone https://git.dracodev.net/Projets/Imago.git /opt/imago
|
||||||
mkdir -p /DOCKER_CONFIG/Imago && cd /DOCKER_CONFIG/Imago
|
cd /opt/imago
|
||||||
# Copier docker-compose.production.yml et .env.production
|
|
||||||
docker compose -f docker-compose.production.yml up -d
|
# 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
|
```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
|
python3 -m venv .venv && source .venv/bin/activate
|
||||||
pip install -r requirements.txt
|
pip install -r requirements.txt
|
||||||
|
cp .env.example .env # Configurer DATABASE_URL, clés AI
|
||||||
# 2. Configuration
|
|
||||||
cp .env.example .env
|
|
||||||
# Éditer .env : DATABASE_URL=sqlite+aiosqlite:///./data/imago.db (pour SQLite local)
|
|
||||||
|
|
||||||
# 3. Démarrer l'API
|
|
||||||
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
|
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é)
|
## Build des images
|
||||||
python worker.py
|
|
||||||
|
```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
|
## Tests
|
||||||
@@ -111,4 +114,15 @@ pip install -r requirements-dev.txt
|
|||||||
pytest tests/ -v
|
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`*
|
||||||
|
|||||||
Reference in New Issue
Block a user