Infrastructure

Rikoo se compose de deux services applicatifs, l'api et le worker, qui reposent sur trois stockages : PostgreSQL, Redis et un stockage objet compatible S3. Deux services optionnels ajoutent l'analyse de documents et les outils embarqués.

Services applicatifs

Service	Rôle	Obligatoire	État
api	API REST, Studio, script du widget, authentification, mise en file d'attente. Applique les migrations de base de données à son démarrage.	Oui	Sans état
worker	Exécute les agents : appels de modèles, recherche documentaire, appels d'outils, e-mails et webhooks.	Oui	Sans état
sidecar-parsing	Extrait le texte des documents PDF et Office. Sans lui, le worker se rabat sur ses propres analyseurs.	Non	Sans état
mcp-sandbox	Les outils embarqués : un espace de travail par conversation et un navigateur. Sans lui, ces outils renvoient une erreur et les exécutions continuent.	Non	Avec état : un espace de travail par conversation
playwright-mcp	Le navigateur piloté par le bac à sable.	Avec le bac à sable	Sans état
mcp-egress	La seule sortie du navigateur du bac à sable, derrière la même garde anti-SSRF que le worker.	Avec le bac à sable	Sans état

L'api et le worker se mettent à l'échelle horizontalement : ils ne conservent aucun état en dehors des stockages.

PostgreSQL

• Version : PostgreSQL 16 est la version testée (les piles de référence utilisent pgvector/pgvector:pg16).
• Extensions : vector (pgvector) et citext. Les index vectoriels utilisent le type halfvec, disponible à partir de pgvector 0.7.0.
• Rôles : les migrations créent les extensions et un rôle rikoo_app, si bien que le rôle qui les exécute doit avoir le droit de créer des extensions et des rôles. Donner un mot de passe à rikoo_app et y faire pointer APP_DATABASE_URL permet à la sécurité au niveau des lignes de filtrer chaque requête sur les données d'une organisation.
• Variables : DATABASE_URL (obligatoire), APP_DATABASE_URL (recommandée).
• Les services PostgreSQL managés conviennent, à condition de proposer pgvector et de laisser le rôle de migration créer des rôles.

Tout se trouve ici sauf les fichiers, vecteurs compris. Sauvegardez cette base.

Redis

• Version : Redis 7.
• Usage : files d'attente des jobs, sessions et compteurs de connexion, et événements qui diffusent une exécution en direct vers le navigateur.
• Configuration : persistance activée (appendonly yes dans les piles de référence) et aucune éviction (maxmemory-policy noeviction) : une clé évincée, c'est un job ou une session perdus.
• Variable : REDIS_URL (obligatoire), redis:// ou rediss://.
• Rikoo se connecte à un seul endpoint Redis, sans mode Cluster ni Sentinel.

Stockage objet

• N'importe quel service compatible S3 : MinIO, fourni avec les deux piles de référence, ou le stockage objet de votre fournisseur cloud.
• Un seul bucket contient les fichiers sources ingérés, les pièces jointes, les sorties d'outils volumineuses et les exports d'audit, chacun sous un préfixe propre à l'organisation.
• Variables : S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID et S3_SECRET_ACCESS_KEY (obligatoires) ; S3_REGION (us-east-1 par défaut, même valeur sur l'api et le worker) ; S3_FORCE_PATH_STYLE (true par défaut) ; S3_BROWSER_ENDPOINT.
• Accès depuis le navigateur : les navigateurs échangent les fichiers directement avec le bucket, par des URL signées, donc S3_BROWSER_ENDPOINT doit être joignable par vos utilisateurs. MinIO accepte toutes les origines par défaut, alors qu'un bucket cloud n'a aucune règle CORS tant que vous n'en ajoutez pas. Autorisez PUT depuis PUBLIC_URL, d'où le Studio envoie les documents, et GET depuis les sites où tourne le widget, qui récupère des fichiers pour « Tout télécharger » et « Copier l'image ».

Réseau

Depuis	Vers	Pourquoi
Utilisateurs	api	Studio, widget, API publique
Utilisateurs	stockage objet	Envoi des pièces jointes, à S3_BROWSER_ENDPOINT
api	PostgreSQL, Redis, votre collecteur de traces	Aucun autre accès sortant
worker	PostgreSQL, Redis, stockage objet	Données
worker	Fournisseurs de modèles, serveurs MCP, cibles de webhooks, serveur SMTP, votre collecteur de traces	Tout ce qui sort de la plateforme

Chaque requête sortante du worker passe par une garde anti-SSRF, qui refuse les adresses privées et link-local. Pour joindre un serveur de modèles sur votre propre réseau, par exemple vLLM ou Ollama, autorisez sa plage d'adresses avec RIKOO_EGRESS_ALLOW_CIDRS, avec la même valeur sur l'api, le worker et mcp-egress. Gardez la plage aussi étroite que possible : chaque entrée ouvre une brèche dans la garde.

Les identifiants des fournisseurs de modèles ne sont pas des variables d'environnement. Ils sont saisis dans le Studio, scellés dans le coffre, et seul le worker peut les ouvrir.

Observabilité

Endpoint	Service	Usage
GET /healthz	api	Liveness : répond tant que le processus tourne, sans solliciter aucune dépendance
GET /readyz	api	Readiness : 503 tant que PostgreSQL et Redis ne répondent pas
GET /api/v1/health	api	Statut et version
GET /health sur le port 3100	worker	Santé du worker, en interne
GET /metrics sur le port 3100	worker	Métriques Prometheus
GET /metrics sur le port 9464	api	Métriques Prometheus, quand OTEL_METRICS_EXPORTER_API=prometheus

Les traces sont exportées en OTLP (HTTP) vers votre propre collecteur. Définissez OTEL_EXPORTER_OTLP_ENDPOINT pour le worker et OTEL_EXPORTER_OTLP_ENDPOINT_API pour l'api. Sans collecteur, rien n'est exporté, et rien n'échoue.