Docker Compose

Ce guide démarre tous les services Rikoo sur une seule machine avec Docker Compose. Utilisez-le pour évaluer Rikoo, faire une démo ou servir une petite équipe. Ses valeurs par défaut sont pensées pour un poste de travail : mots de passe de base de données par défaut, et PostgreSQL, Redis et MinIO publiés sur l'hôte. Pour la production, déployez sur Kubernetes, ou durcissez la pile comme décrit dans Avant de l'exposer.

Prérequis

• Un accès au dépôt source de Rikoo, Rikoo-app/rikoo (voir la Vue d'ensemble).
• Docker Engine avec Docker Compose 2.20 ou ultérieur.
• Node.js 20 ou ultérieur et pnpm sur l'hôte : ils servent à générer les clés et à construire le Studio.
• Des ports libres sur l'hôte : 3000 (api et Studio), 5432 (PostgreSQL), 6379 (Redis), 9000 et 9001 (MinIO).

Installation

1. Récupérer le code source

Placez-vous sur une version publiée plutôt que sur main, qui contient des changements pas encore publiés.

git clone https://github.com/Rikoo-app/rikoo.git
cd rikoo
git checkout v0.2.0

2. Construire le Studio et le widget

Le conteneur api sert le Studio et le script du widget depuis les dossiers web/dist et widget/lib/dist de cette copie de travail, montés dans le conteneur. Construisez-les avant le premier démarrage, le widget en premier :

make install
pnpm --filter @rikoo/widget build
pnpm --filter @rikoo/web build:localized

attention

Sans cette étape, la pile démarre et se déclare en bonne santé, mais http://localhost:3000 ne sert aucun Studio et /widget/widget.js est absent.

3. Configurer

La pile lit deploy/compose/.env. Partez du fichier d'exemple, puis renseignez les valeurs qu'il laisse vides :

cp deploy/compose/.env.example deploy/compose/.env
make secrets-keys     # affiche RIKOO_SECRETS_PUBLIC_KEY et RIKOO_SECRETS_PRIVATE_KEY
make sandbox-secret   # affiche MCP_SANDBOX_TOKEN_SECRET
node -e "console.log('WIDGET_SIGNING_KEY=' + require('node:crypto').randomBytes(32).toString('base64'))"
chmod 600 deploy/compose/.env

Copiez chaque ligne affichée dans deploy/compose/.env, à la place de la ligne vide du même nom.

Variable	Obligatoire	Rôle
RIKOO_SECRETS_PUBLIC_KEY, RIKOO_SECRETS_PRIVATE_KEY	Oui	La paire de clés de scellement du coffre. L'api scelle les secrets avec la clé publique, et seul le worker détient la clé privée. Perdre la clé privée rend illisibles tous les secrets stockés.
MCP_SANDBOX_TOKEN_SECRET	Oui	Authentifie le worker auprès du bac à sable des outils. Compose refuse de démarrer sans elle.
WIDGET_SIGNING_KEY	Oui, en pratique	Signe les sessions du widget, et sert à dériver les clés qui protègent les secrets d'authentification à deux facteurs et la licence stockée. Quand elle est vide, Compose se rabat sur une valeur de développement publique. Définissez-la une fois pour toutes, avant le premier compte : la changer ensuite invalide ce qui en a été dérivé.
PUBLIC_URL	Non, http://localhost:3000 par défaut	L'adresse que saisissent les utilisateurs. C'est la seule origine que l'api accepte pour les requêtes du Studio, et la base des liens contenus dans les e-mails.
TRUST_PROXY_HOPS	Oui, fixée à 0 dans l'exemple	0 quand l'api est jointe directement, 1 derrière un proxy inverse.

Quand une variable obligatoire est vide, Compose refuse de démarrer et la nomme : required variable MCP_SANDBOX_TOKEN_SECRET is missing a value.

Pour remplacer les mots de passe par défaut de la base de données et du stockage, définissez POSTGRES_PASSWORD et MINIO_ROOT_PASSWORD dès maintenant : PostgreSQL conserve le mot de passe avec lequel son volume a été créé.

4. Démarrer

make up

Cette commande exécute docker compose -f deploy/compose/docker-compose.yml up --build -d. Le premier lancement construit les images de l'api, du worker et du bac à sable depuis les sources, et prend plusieurs minutes. L'api applique les migrations de base de données à chaque démarrage : il n'y a donc pas d'étape de migration séparée.

5. Vérifier

curl http://localhost:3000/api/v1/health
curl -i http://localhost:3000/readyz      # 200 dès que PostgreSQL et Redis répondent, 503 sinon

6. Créer le premier compte

Ouvrez PUBLIC_URL (par défaut http://localhost:3000) et inscrivez-vous. Tant qu'aucune organisation n'existe, le premier compte peut s'inscrire et créer la première organisation, dont il devient Propriétaire. Un mot de passe compte au moins 10 caractères. Toutes les personnes suivantes arrivent sur invitation.

Ce qui tourne

Service	Rôle	Obligatoire
api	API REST, Studio, widget, authentification	Oui
worker	Exécutions, appels de modèles, recherche documentaire, outils, appels sortants	Oui
postgres	Données et vecteurs (pgvector/pgvector:pg16)	Oui
redis	Files d'attente, sessions, pub/sub (redis:7-alpine)	Oui
minio, minio-setup	Stockage compatible S3 ; minio-setup crée le bucket rikoo puis s'arrête	Oui
sidecar-parsing	Extraction des documents PDF et Office	Non
mcp-sandbox, playwright-mcp, mcp-egress	Outils embarqués : l'espace de travail isolé, le navigateur, et le proxy par lequel sort le navigateur	Non

Les services optionnels démarrent par défaut. Quand l'un d'eux manque, la fonctionnalité qu'il porte est dégradée et les exécutions continuent. Infrastructure décrit chaque service en détail.

Le bac à sable tourne avec un profil seccomp dédié. Sur un hôte Linux, vous pouvez ajouter gVisor comme seconde couche d'isolation : la ligne runtime: runsc du service mcp-sandbox est prête à être décommentée une fois gVisor installé.

Édition Enterprise

L'édition Enterprise est un autre build des images api et worker. Déclarez-la dans deploy/compose/.env, puis reconstruisez :

RIKOO_EDITION=ee

make up

Gardez la ligne dans .env : sans elle, le prochain make up reconstruit des images Community. Activez ensuite votre licence, voir Licence Enterprise.

Avant de l'exposer

La configuration d'exemple est pensée pour un poste de travail. Avant que quiconque d'autre accède à la machine :

• Placez l'api derrière un proxy inverse qui assure la terminaison TLS, donnez à PUBLIC_URL son adresse publique et fixez TRUST_PROXY_HOPS=1.
• Cessez de publier PostgreSQL et Redis sur l'hôte : supprimez leurs entrées ports dans deploy/compose/docker-compose.yml.
• N'exposez MinIO qu'à travers votre proxy, et donnez cette adresse à S3_BROWSER_ENDPOINT : les navigateurs y envoient directement les pièces jointes, si bien que la valeur par défaut http://localhost:9000 échoue pour tout autre utilisateur.
• Vérifiez que POSTGRES_PASSWORD et MINIO_ROOT_PASSWORD n'ont pas leurs valeurs par défaut (voir Configurer).
• Sauvegardez les volumes pgdata et miniodata, ainsi que la clé privée de scellement.

Exploitation

Tâche	Commande
Suivre les journaux	make logs
Appliquer une modification de .env	make up (recrée les conteneurs concernés ; un simple docker compose restart ne relit pas .env)
Arrêter en conservant les données	make down
Arrêter et supprimer toutes les données	make clean (supprime les volumes pgdata, redisdata, miniodata et sandboxdata)

Mise à jour

Sauvegardez d'abord la base de données. Placez-vous ensuite sur la nouvelle version, reconstruisez le Studio et redémarrez :

git fetch --tags
git checkout v0.2.0      # la version vers laquelle vous mettez à jour
pnpm --filter @rikoo/widget build
pnpm --filter @rikoo/web build:localized
make up

L'api applique les migrations en attente à son démarrage. Lisez les notes de version avant de mettre à jour : une version peut rendre une variable obligatoire.

Dépannage

Symptôme	Cause et correction
required variable ... is missing a value	Une variable obligatoire est vide dans deploy/compose/.env. Voir Configurer.
Les endpoints de santé répondent, mais http://localhost:3000 n'affiche aucun Studio	Le Studio n'a pas été construit sur l'hôte. Exécutez l'étape 2, puis make up.
port is already allocated	Un autre processus utilise le port 3000, 5432, 6379, 9000 ou 9001. Arrêtez-le, ou changez le port publié dans le fichier compose.
Le worker ne joint pas un serveur de modèles de votre réseau	La garde de sortie refuse les adresses privées. Autorisez la plage avec RIKOO_EGRESS_ALLOW_CIDRS dans deploy/compose/.env, par exemple 10.0.0.0/8. Compose la transmet à chaque service qui applique la garde.