Installation locale

Objectif

Faire tourner Finoptika sur votre machine (API + PostgreSQL + dashboard React) pour évaluer la plateforme ou développer. Public : SRE, platform engineer, développeur.

Prérequis

Outil	Version	Rôle
Docker Desktop	récent	PostgreSQL, Redis, Qdrant
Python	3.12+	API backend
Node.js	20+	SPA frontend
Make	quelconque	Commandes de confort (optionnel)

Démarrage rapide (recommandé)

cd finoptica-next

# 1. Infra Docker + install deps + migrations Alembic
make setup

# 2. Terminal A — API sur :8000 (hot-reload)
make dev-api

# 3. Terminal B — Frontend sur :5173
make dev-frontend

# 4. Ouvrir l'application
open http://localhost:5173

Connectez-vous avec Acme Admin (permissions complètes) ou Globex Viewer (tenant en lecture seule).

Variantes de setup

• make setup-backend — backend uniquement (sans npm).
• make setup-no-docker — sans Docker (nécessite un PostgreSQL local sur :5432, user/db/pass finoptica).

Services d'infrastructure

Service	Port	Notes
PostgreSQL	5432	user/pass/db : finoptica
Redis	6379	workers Celery (optionnel en dev)
Qdrant	6333	RAG copilot (optionnel)

Installation manuelle (étape par étape)

# 1. Infrastructure
docker compose -f deploy/local/docker-compose.yml up -d
docker compose -f deploy/local/docker-compose.yml ps   # attendre PostgreSQL healthy

# 2. Backend
cd backend
python3 -m venv .venv && source .venv/bin/activate   # Windows : .venv\Scripts\activate
pip install -e .
alembic upgrade head
uvicorn app.main:app --reload --port 8000

# 3. Frontend (autre terminal)
cd frontend && npm install && npm run dev

Vérifier l'installation

• API / Swagger (dev) : http://localhost:8000/docs
• Frontend : http://localhost:5173
• Santé : voir la page Santé plateforme une fois connecté.

Authentification en développement

• Mode HS256 JWT minté par POST /api/v1/dev/token (persona admin ou viewer), disponible quand APP_ENV=development.
• La page de login appelle ce endpoint et stocke le JWT en localStorage.

Charger des données

Aucune donnée n'est visible tant que rien n'est ingéré :

1. Connectez-vous en admin.
2. Suivez Ingest & mapping pour importer un fichier de coûts.
3. Refresh les dashboards.

Dépannage

Symptôme	Cause probable	Résolution
getcwd EPERM avec les outils preview	cwd non défini	Renseigner cwd explicite dans .claude/launch.json
Port 8000/5173 occupé	Autre process	Libérer le port ou changer --port
PostgreSQL non healthy	Conteneur pas prêt	Attendre ; docker compose ps
Dashboards vides	Aucune donnée ingérée	Lancer un ingest

Voir aussi

• Déploiement production
• Ingest & mapping
• Référence dépôt : docs/LOCALHOST.md, docs/HOW_TO_USE_IT.md