Hébergement avec Docker

Docker Compose est le moyen le plus rapide d'exécuter une instance du Registre Sannvit, qu'il s'agisse d'un environnement de développement local ou d'un déploiement de production sur un seul hôte. Tout ce qui suit suppose que vous avez déjà cloné le dépôt.

Prérequis

• Docker + Docker Compose
• Node.js — pour appliquer les migrations de base de données et (optionnellement) pour le développement natif hors conteneurs

Contenu des fichiers compose

La pile est répartie entre un fichier de base et des surcouches (overrides) que vous ajoutez selon vos besoins :

L'application communique directement avec Postgres en clair et Keycloak gère l'authentification — sans services supplémentaires entre les deux — ce qui garde une empreinte assez réduite pour être installée sur l'infrastructure propre d'un client.

1. Configurez votre environnement

.env se trouve à la racine du dépôt et est lu par chaque fichier compose.

cp .env.example .env

Au minimum, renseignez ces secrets avant de démarrer quoi que ce soit — openssl rand -hex 24 pour chacun :

• POSTGRES_PASSWORD
• JWT_SECRET
• KEYCLOAK_ADMIN_PASSWORD
• KEYCLOAK_SERVICE_CLIENT_SECRET
• S3_ROOT_PASSWORD (nécessaire uniquement si vous utilisez le stockage d'objets fourni)
• EXPORT_SECRET_KEY (nécessaire uniquement avant d'utiliser la fonctionnalité d'export SFTP des dossiers de preuves)

Des valeurs réservées au développement conviennent pour un usage local — évitez simplement de les réutiliser dans un contexte réel.

2. Démarrez la pile

Développement

docker/run.sh gère les fichiers de surcouche compose actifs et lit toujours .env depuis la racine du dépôt, quel que soit le répertoire de travail de votre shell :

cd docker
./run.sh config add keycloak rustfs mail api api.dev dashboard dashboard.dev
./run.sh start

api.dev / dashboard.dev ajoutent le rechargement à chaud (source montée en bind-mount, tsx watch / HMR Nuxt) par-dessus leurs services de base.

Production (hôte unique)

npm run prod

ce qui équivaut à :

cd docker
COMPOSE_FILE=docker-compose.yml:docker-compose.keycloak.yml:docker-compose.rustfs.yml:docker-compose.api.yml:docker-compose.dashboard.yml \
COMPOSE_ENV_FILES=../.env COMPOSE_IGNORE_ORPHANS=true \
docker compose up -d --wait --build

!WARNING Avant de faire cela en conditions réelles :

• Les valeurs de .env.example sont des exemples, pas des secrets — définissez des valeurs réelles et uniques pour chaque entrée listée ci-dessus.
• Placez un véritable proxy inverse avec terminaison TLS devant la pile (docker-compose.nginx.yml ou .caddy.yml) plutôt que d'exposer les ports bruts des services, et définissez PROXY_DOMAIN dans .env.
• Changez le secret du client ledger-service de Keycloak par rapport à la valeur par défaut de développement de l'export du royaume (docker/volumes/keycloak/ledger-realm.json) via la console d'administration Keycloak, et mettez à jour KEYCLOAK_SERVICE_CLIENT_SECRET dans .env en conséquence.
• Faites pointer SMTP_* vers un vrai relais plutôt que Mailpit, et définissez DASHBOARD_URL sur le domaine public réel du tableau de bord — voir E-mail (SMTP) ci-dessous.
• Mettez en place des procédures de sauvegarde appropriées pour le volume db.

3. Appliquez le schéma de base de données

Il s'agit d'une étape unique par base de données neuve — elle ne fait pas partie de run.sh start. Attendez que db et keycloak signalent un état sain (./run.sh status), puis, depuis la racine du dépôt :

for f in api/drizzle/0*.sql; do
  psql -h localhost -U postgres -d postgres -v ON_ERROR_STOP=1 -f "$f"
done

cd api
npm install
npm run db:functions   # applique src/db/functions/*.sql — pas les objets drizzle-kit
npm run seed:demo      # org + équipe + clé d'ingestion de démo (la clé est affichée une fois, conservez-la)

Aucun utilisateur du tableau de bord n'est initialisé par défaut — seed:demo crée uniquement une organisation/équipe/clé d'ingestion de démo pour le côté SDK. Pour obtenir une connexion humaine, initialisez plutôt le premier administrateur (depuis api/, une fois db et keycloak démarrés et les migrations appliquées) :

npm run seed:admin -- you@example.com --org-name="Your Org Name"

Cela affiche un mot de passe généré, une seule fois. Chaque utilisateur suivant est invité via le tableau de bord (Organisation → Utilisateurs → Inviter) par un compliance_admin existant, et non via ce script.

4. C'est prêt

• Dashboard — http://localhost:3000
• Ledger API — http://localhost:4010 (GET /healthz)
• Administration Keycloak — http://localhost:8180
• Mailpit (intercepteur d'e-mails de développement) — http://localhost:8025
• Console du stockage d'objets — http://localhost:9001 (RustFS fourni, si vous l'avez conservé)

Commandes run.sh utiles

./run.sh logs [service]     # suivre les logs
./run.sh status             # docker compose ps
./run.sh recreate [service] # forcer la recréation d'un service
./run.sh stop                # tout arrêter

Appeler docker compose directement plutôt que run.sh nécessite d'indiquer explicitement le fichier d'environnement, par exemple depuis la racine du dépôt :

docker compose --env-file .env -f docker/docker-compose.yml -f docker/docker-compose.keycloak.yml up -d

Utiliser votre propre stockage compatible S3

Par défaut, la pile fournit un conteneur RustFS comme stockage d'objets pour le contenu des payloads — le registre lui-même ne stocke qu'un pointeur + un hash. Si vous préférez pointer vers un bucket existant (AWS S3, Cloudflare R2, Backblaze B2, votre propre MinIO/RustFS, etc.) :

1. N'ajoutez pas la surcouche rustfs — n'exécutez pas ./run.sh config add rustfs, ou exécutez ./run.sh config remove rustfs si elle est déjà présente.
2. Dans .env, définissez S3_ENDPOINT, S3_PORT, S3_USE_SSL, et optionnellement S3_REGION vers le fournisseur externe, ainsi que S3_ACCESS_KEY / S3_SECRET_KEY avec des identifiants restreints à ce bucket. Définissez LEDGER_BUCKET avec le nom du bucket.
3. Le bucket est créé de manière différée lors du premier envoi s'il n'existe pas déjà — donc soit vous le pré-créez, soit vous accordez aux identifiants fournis la permission CreateBucket.

Le second plan d'intégrité en ajout seul est un second bucket (LEDGER_INTEGRITY_BUCKET, par défaut ledger-integrity) sur le même endpoint, créé avec le verrouillage d'objets S3 (Object Lock) activé — indélébile pendant sa fenêtre de rétention, même par les administrateurs.

!CAUTION Le conteneur RustFS fourni comporte des bugs ouverts dans son implémentation d'Object Lock. C'est acceptable pour le développement, mais les déploiements de production devraient faire pointer LEDGER_INTEGRITY_BUCKET vers une implémentation mature d'Object Lock via l'option « apportez votre propre S3 » — AWS S3 réel, Backblaze B2, ou GCS via l'interopérabilité S3.

E-mail (SMTP)

L'API du registre envoie les e-mails d'invitation, de réinitialisation de mot de passe et de synthèse d'alertes via SMTP.

Développement local — capturez les e-mails au lieu de les envoyer :

./run.sh config add mail
./run.sh start

Chaque e-mail atterrit sur http://localhost:8025 (Mailpit) au lieu d'une vraie boîte de réception.

Production — livrer de vrais e-mails :

1. Obtenez des identifiants SMTP auprès d'un fournisseur d'e-mail (SendGrid, Postmark, AWS SES, Resend, Mailgun, ou un relais d'entreprise existant).
2. Définissez SMTP_ADMIN_EMAIL, SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, et SMTP_SENDER_NAME dans le .env de cet environnement. Laissez SMTP_ALLOW_INSECURE_AUTH non défini — il n'existe que pour Mailpit.
3. Définissez DASHBOARD_URL sur le domaine public réel du tableau de bord — il est intégré dans les liens des e-mails d'invitation/réinitialisation.
4. N'ajoutez pas la surcouche mail en production, sinon elle interceptera le courrier réel.
5. Appliquez le changement : ./run.sh recreate api alerting.

Si votre fournisseur exige une vérification de domaine (SPF/DKIM, identité de l'expéditeur — courant avec SES et Postmark), celle-ci doit être effectuée du côté du fournisseur avant que le courrier ne soit réellement livré.

Mise à jour

1. Consultez le journal des modifications pour les changements incompatibles dans les images utilisées par cette pile (Postgres, Keycloak, RustFS, Mailpit).
2. Mettez à jour les tags d'images dans le docker-compose.*.yml concerné si nécessaire.
3. Récupérez les dernières images : docker compose pull.
4. Reconstruisez api / dashboard si leur code source a changé : docker compose -f docker-compose.api.yml -f docker-compose.dashboard.yml up -d --build.

Sauvegardez toujours votre base de données avant une mise à jour.

Besoin d'une mise à l'échelle horizontale ?

Pour un déploiement en cluster au-delà d'un seul hôte Compose, il existe un chemin Kubernetes basé sur Helm — construction/publication des images, secrets, DNS, et helm install — traité séparément de Docker Compose.