Docker Compose

Esta guía arranca todos los servicios de Rikoo en una sola máquina con Docker Compose. Úsela para evaluar Rikoo, hacer una demo o dar servicio a un equipo pequeño. Sus valores por defecto están pensados para una estación de trabajo: contraseñas de base de datos por defecto, y PostgreSQL, Redis y MinIO publicados en el host. Para producción, despliegue en Kubernetes o refuerce la pila como se describe en Antes de exponerla.

Requisitos

• Acceso al repositorio de código fuente de Rikoo, Rikoo-app/rikoo (consulte la Visión general).
• Docker Engine con Docker Compose 2.20 o posterior.
• Node.js 20 o posterior y pnpm en el host: sirven para generar las claves y compilar el Studio.
• Puertos libres en el host: 3000 (api y Studio), 5432 (PostgreSQL), 6379 (Redis), 9000 y 9001 (MinIO).

Instalación

1. Obtener el código fuente

Use una versión publicada en lugar de main, que contiene cambios aún no publicados.

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

2. Compilar el Studio y el widget

El contenedor de la api sirve el Studio y el script del widget desde las carpetas web/dist y widget/lib/dist de esta copia de trabajo, montadas en el contenedor. Compílelas antes del primer arranque, empezando por el widget:

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

aviso

Sin este paso la pila arranca y se declara en buen estado, pero http://localhost:3000 no sirve ningún Studio y falta /widget/widget.js.

3. Configurar

La pila lee deploy/compose/.env. Parta del archivo de ejemplo y rellene los valores que deja vacíos:

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

Copie cada línea mostrada en deploy/compose/.env, en lugar de la línea vacía del mismo nombre.

Variable	Obligatoria	Qué es
RIKOO_SECRETS_PUBLIC_KEY, RIKOO_SECRETS_PRIVATE_KEY	Sí	El par de claves de sellado de la bóveda. La api sella los secretos con la clave pública y solo el worker tiene la clave privada. Perder la clave privada hace ilegibles todos los secretos almacenados.
MCP_SANDBOX_TOKEN_SECRET	Sí	Autentica el worker ante el entorno aislado de las herramientas. Compose se niega a arrancar sin ella.
WIDGET_SIGNING_KEY	Sí, en la práctica	Firma las sesiones del widget y sirve para derivar las claves que protegen los secretos de la autenticación de dos factores y la licencia almacenada. Cuando está vacía, Compose recurre a un valor público de desarrollo. Defínala una sola vez, antes de la primera cuenta: cambiarla después invalida lo que se derivó de ella.
PUBLIC_URL	No, http://localhost:3000 por defecto	La dirección que escriben los usuarios. Es el único origen que la api acepta para las peticiones del Studio y la base de los enlaces de los correos electrónicos.
TRUST_PROXY_HOPS	Sí, con valor 0 en el ejemplo	0 cuando se accede a la api directamente, 1 detrás de un proxy inverso.

Cuando una variable obligatoria está vacía, Compose se niega a arrancar y la nombra: required variable MCP_SANDBOX_TOKEN_SECRET is missing a value.

Para sustituir las contraseñas por defecto de la base de datos y del almacenamiento, defina POSTGRES_PASSWORD y MINIO_ROOT_PASSWORD ahora: PostgreSQL conserva la contraseña con la que se creó su volumen.

4. Arrancar

make up

Esto ejecuta docker compose -f deploy/compose/docker-compose.yml up --build -d. El primer arranque compila las imágenes de la api, del worker y del entorno aislado desde el código fuente y tarda varios minutos. La api aplica las migraciones de la base de datos cada vez que arranca, así que no hay un paso de migración aparte.

5. Comprobar

curl http://localhost:3000/api/v1/health
curl -i http://localhost:3000/readyz      # 200 en cuanto PostgreSQL y Redis responden, 503 si no

6. Crear la primera cuenta

Abra PUBLIC_URL (por defecto http://localhost:3000) y regístrese. Mientras no exista ninguna organización, la primera cuenta puede registrarse y crear la primera organización, en la que obtiene el rol Owner (propietario). Las contraseñas deben tener al menos 10 caracteres. Todos los demás entran por invitación.

Qué se ejecuta

Servicio	Función	Obligatorio
api	API REST, Studio, widget, autenticación	Sí
worker	Ejecuciones, llamadas a modelos, búsqueda documental, herramientas, llamadas salientes	Sí
postgres	Datos y vectores (pgvector/pgvector:pg16)	Sí
redis	Colas, sesiones, pub/sub (redis:7-alpine)	Sí
minio, minio-setup	Almacenamiento compatible con S3; minio-setup crea el bucket rikoo y termina	Sí
sidecar-parsing	Extracción de documentos PDF y de Office	No
mcp-sandbox, playwright-mcp, mcp-egress	Herramientas integradas: el espacio de trabajo aislado, el navegador y el proxy por el que sale el navegador	No

Los servicios opcionales arrancan por defecto. Cuando falta uno, la función que aporta se degrada y las ejecuciones continúan. Infraestructura describe cada servicio en detalle.

El entorno aislado se ejecuta con un perfil seccomp dedicado. En hosts Linux puede añadir gVisor como segunda capa de aislamiento: la línea runtime: runsc del servicio mcp-sandbox está lista para descomentarse una vez instalado gVisor.

Edición Enterprise

La edición Enterprise es otra compilación de las imágenes de la api y del worker. Defínala en deploy/compose/.env y vuelva a compilar:

RIKOO_EDITION=ee

make up

Mantenga la línea en .env: sin ella, el siguiente make up vuelve a compilar imágenes Community. Después active su licencia, consulte Licencia Enterprise.

Antes de exponerla

La configuración de ejemplo está pensada para una estación de trabajo. Antes de que cualquier otra persona acceda a la máquina:

• Coloque la api detrás de un proxy inverso que haga la terminación TLS, asigne a PUBLIC_URL su dirección pública y defina TRUST_PROXY_HOPS=1.
• Deje de publicar PostgreSQL y Redis en el host: elimine sus entradas ports en deploy/compose/docker-compose.yml.
• Exponga MinIO solo a través de su proxy y asigne esa dirección a S3_BROWSER_ENDPOINT: los navegadores suben los adjuntos directamente a ella, de modo que el valor por defecto http://localhost:9000 falla para cualquier otra persona.
• Asegúrese de que POSTGRES_PASSWORD y MINIO_ROOT_PASSWORD no conservan los valores por defecto (consulte Configurar).
• Haga copias de seguridad de los volúmenes pgdata y miniodata y de la clave privada de sellado.

Operación

Tarea	Comando
Seguir los registros	make logs
Aplicar un cambio en .env	make up (recrea los contenedores afectados; un simple docker compose restart no vuelve a leer .env)
Detener conservando los datos	make down
Detener y eliminar todos los datos	make clean (elimina los volúmenes pgdata, redisdata, miniodata y sandboxdata)

Actualización

Haga primero una copia de seguridad de la base de datos. Después cambie a la nueva versión, vuelva a compilar el Studio y reinicie:

git fetch --tags
git checkout v0.2.0      # la versión a la que actualiza
pnpm --filter @rikoo/widget build
pnpm --filter @rikoo/web build:localized
make up

La api aplica las migraciones pendientes al arrancar. Lea las notas de la versión antes de actualizar: una versión puede volver obligatoria una variable.

Resolución de problemas

Síntoma	Causa y solución
required variable ... is missing a value	Una variable obligatoria está vacía en deploy/compose/.env. Consulte Configurar.
El estado de salud es correcto, pero http://localhost:3000 no muestra ningún Studio	El Studio no se compiló en el host. Ejecute el paso 2 y después make up.
port is already allocated	Otro proceso usa el puerto 3000, 5432, 6379, 9000 o 9001. Deténgalo o cambie el puerto publicado en el archivo de Compose.
El worker no llega a un servidor de modelos de su red	La protección de salida rechaza las direcciones privadas. Autorice el rango con RIKOO_EGRESS_ALLOW_CIDRS en deploy/compose/.env, por ejemplo 10.0.0.0/8. Compose lo pasa a cada servicio que aplica la protección.