Desplegar con Docker
Corre el motor de Sypnia en cualquier servidor con Docker Compose, junto a un Postgres y un almacenamiento compatible con S3, con HTTPS, un primer proyecto, sus llaves y una comprobación de salud.
En esta página
- Qué corre
- Desplegar
- Apunta dos nombres al servidor
- Escribe los secretos
- Escribe el archivo de Compose
- Escribe el archivo de Caddy
- Arráncalo
- Comprueba su salud
- Corre el doctor
- Crea el primer proyecto
- Crea una llave para cada app adicional, y un token para leer
- Envía desde tu app y mira cómo llega
- Usar un bucket o una base de datos alojados
- Amazon S3
- Cloudflare R2
- Dejar que los navegadores lean grabaciones de un bucket alojado
- Un Postgres alojado
- El día a día
- Eliminar todo
- Cuando algo falla
- Sigue con esto
Motor Esta página es para quien corre el motor de código abierto en un servidor propio, en cualquier proveedor. No aplica a Sypnia Cloud. Para una prueba en tu computador, sin HTTPS, usa el inicio rápido con alojamiento propio, que es más corto; para AWS sin servidor, Desplegar en AWS.
Al final tendrás: el motor en https://sypnia.example.com como un solo proceso de larga duración, un Postgres y un almacenamiento compatible con S3 a su lado, certificados que se renuevan solos, un primer proyecto con una llave de ingesta y un token de API, y sypnia doctor en verde.
Necesitas: un servidor Linux con Docker y Compose, alcanzable desde internet por los puertos 80 y 443 (2 vCPU, 4 GB de memoria y 40 GB de disco es un comienzo sensato; ver Escalado y costo); dos nombres de DNS que apunten a él; openssl; unos 30 minutos.
Qué corre
| Servicio | Imagen | Qué hace | Se alcanza desde fuera |
|---|---|---|---|
sypnia | ghcr.io/sypnia/sypnia:1 | El motor completo en un proceso: sypnia serve con el rol all. | Solo a través de caddy |
db | postgres:16 | La base de datos. | No |
minio | minio/minio | El almacenamiento compatible con S3 que guarda el bucket. | Solo a través de caddy, para los enlaces de grabaciones y la subida de source maps |
bucket | minio/mc | Crea el bucket una vez y termina. | No |
caddy | caddy:2 | HTTPS delante del motor y del almacenamiento, con certificados que consigue y renueva solo. | Puertos 80 y 443 |
Hacen falta dos nombres de DNS porque los navegadores leen las grabaciones, y tu CI sube los source maps, directo del almacenamiento con enlaces firmados de corta duración. Con un almacenamiento alojado, como Amazon S3 o Cloudflare R2, solo necesitas un nombre: ver Usar un bucket o una base de datos alojados.
Desplegar
Apunta dos nombres al servidor
En tu proveedor de DNS, crea dos registros
Acon la dirección del servidor:Nombre Para sypnia.example.comEl motor: los SDK, la API, el servidor MCP, la Consola storage.sypnia.example.comEl almacenamiento: enlaces de grabaciones y subida de source maps Terminal dig +short sypnia.example.com storage.sypnia.example.comDeberías verLa dirección del servidor, dos veces.Escribe los secretos
En una carpeta vacía del servidor:
Terminal cat > .env <<EOF SYPNIA_DOMAIN=sypnia.example.com STORAGE_DOMAIN=storage.sypnia.example.com SYPNIA_ROOT_TOKEN=$(openssl rand -hex 32) POSTGRES_PASSWORD=$(openssl rand -hex 24) MINIO_PASSWORD=$(openssl rand -hex 24) EOF chmod 600 .envDeberías verUn archivo.envcon cinco líneas que solo tú puedes leer. Copia el token raíz a tu gestor de contraseñas: puede hacer todo en todos los proyectos.Escribe el archivo de Compose
compose.yaml services: sypnia: image: ghcr.io/sypnia/sypnia:1 restart: unless-stopped environment: SYPNIA_BASE_URL: https://${SYPNIA_DOMAIN} SYPNIA_ROOT_TOKEN: ${SYPNIA_ROOT_TOKEN} SYPNIA_AUTO_MIGRATE: "true" SYPNIA_TRUSTED_PROXY_HOPS: "1" SYPNIA_DATABASE_URL: postgres://sypnia:${POSTGRES_PASSWORD}@db:5432/sypnia SYPNIA_STORAGE_BUCKET: sypnia SYPNIA_STORAGE_ENDPOINT: http://minio:9000 SYPNIA_STORAGE_PUBLIC_ENDPOINT: https://${STORAGE_DOMAIN} SYPNIA_STORAGE_PATH_STYLE: "true" SYPNIA_STORAGE_ACCESS_KEY_ID: sypnia SYPNIA_STORAGE_SECRET_ACCESS_KEY: ${MINIO_PASSWORD} depends_on: db: { condition: service_healthy } bucket: { condition: service_completed_successfully } db: image: postgres:16 restart: unless-stopped environment: POSTGRES_USER: sypnia POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} POSTGRES_DB: sypnia volumes: ["db:/var/lib/postgresql/data"] healthcheck: test: ["CMD-SHELL", "pg_isready -U sypnia"] interval: 5s retries: 20 minio: image: minio/minio restart: unless-stopped command: server /data environment: MINIO_ROOT_USER: sypnia MINIO_ROOT_PASSWORD: ${MINIO_PASSWORD} volumes: ["bucket:/data"] bucket: image: minio/mc depends_on: [minio] environment: MINIO_PASSWORD: ${MINIO_PASSWORD} entrypoint: > sh -c "until mc alias set local http://minio:9000 sypnia $$MINIO_PASSWORD; do sleep 1; done; mc mb --ignore-existing local/sypnia" caddy: image: caddy:2 restart: unless-stopped ports: ["80:80", "443:443"] environment: SYPNIA_DOMAIN: ${SYPNIA_DOMAIN} STORAGE_DOMAIN: ${STORAGE_DOMAIN} volumes: - ./Caddyfile:/etc/caddy/Caddyfile:ro - caddy:/data depends_on: [sypnia, minio] volumes: db: bucket: caddy:Cada línea
SYPNIA_…es un ajuste de la referencia de configuración. Tres de ellas cambian respecto al inicio rápido, y cada una importa:SYPNIA_BASE_URLes la dirección pública con HTTPS. Queda escrita en los enlaces, y es donde vive la Consola.SYPNIA_TRUSTED_PROXY_HOPSes1porque hay un proxy, Caddy, delante del motor. Con0todos los visitantes compartirían un solo límite de peticiones: la dirección de Caddy.SYPNIA_STORAGE_PUBLIC_ENDPOINTes la dirección que usan los navegadores para el almacenamiento. El motor sigue usandohttp://minio:9000, dentro de la red de Compose.
SYPNIA_AUTO_MIGRATEestá entruepara que el motor cree y actualice sus tablas al arrancar. Es lo correcto para un solo proceso. Si más adelante corres varios, ponlo enfalsey corresypnia migratecomo un paso de tu despliegue.Escribe el archivo de Caddy
Caddyfile {$SYPNIA_DOMAIN} { reverse_proxy sypnia:8080 } {$STORAGE_DOMAIN} { reverse_proxy minio:9000 }En lugar de Caddy sirve cualquier proxy inverso o balanceador de carga con TLS. Tiene que pasar el encabezado
Hostsin cambios al almacenamiento, o los enlaces firmados dejan de coincidir.Comprueba su salud
Terminal curl -i https://sypnia.example.com/healthzDeberías verHTTP/2 200. La primera vez, dale a Caddy hasta un minuto para conseguir los certificados./healthzresponde200cuando el proceso está arriba y atendiendo; apunta ahí tu balanceador de carga o tu propio monitor. No prueba la base de datos ni el bucket: eso lo hacesypnia doctor, en el paso siguiente.Corre el doctor
Terminal docker compose exec sypnia sypnia doctor --skip aiDeberías verText config ok 11 settings read, 0 unknown database ok postgres 16.4, schema 12 (up to date), 2 ms storage ok s3://sypnia: put, get, delete, presign address ok https://sypnia.example.com/healthz answered 200 webhook skip SYPNIA_ALERT_WEBHOOK_URL is not set (alerts are recorded only) clock ok 0.1 s from the database's clock all checks passedUna línea que dice
FAILnombra el ajuste que hay que cambiar. La revisión de IA se omite porque todavía no hay un modelo conectado.Crea el primer proyecto
Terminal docker compose exec sypnia sypnia project create --name ShopDeberías verText project shop (prj_5k2m9x4q7w1z) ingest key spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e Put the ingest key in your app. It is public: it can only send. Next: sypnia token create --project shop --name "My laptop" --scopes read,replayEl comando usa el token raíz que encuentra en el entorno del contenedor. La llave de ingesta que imprime es la que usa tu app de navegador para enviar.
Crea una llave para cada app adicional, y un token para leer
Dale a tu servidor su propia llave de ingesta, para poder revocar una sin detener la otra:
Terminal docker compose exec sypnia sypnia key create --project shop --name "Checkout API"Deberías verText key_8b5n2m7v4c1x spk_a3c9e1f7b5d2084c6e0a9f3b7d1c5e82 Checkout APILuego un token de API, para leer lo que llega desde la Consola, la CLI o tu agente de código:
Terminal docker compose exec sypnia sypnia token create --project shop --name "My laptop" --scopes read,replayDeberías verUna línea que empieza porsps_. Se muestra una sola vez: cópiala ahora. Es un secreto.Envía desde tu app y mira cómo llega
Apunta el SDK a tu motor con
endpoint:src/main.ts import { init } from '@sypnia/browser'; init({ project: 'spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e', endpoint: 'https://sypnia.example.com', environment: location.hostname === 'localhost' ? 'development' : 'production', });Abre tu app, haz clic en algunas cosas, luego abre
https://sypnia.example.com/consoley pega tu token de API.Deberías verEn menos de 10 minutos, tu sesión en la Consola. En menos de 2 minutos desde un primer error, un problema. Tu primer problema te lleva a provocar uno a propósito.
Antes de recibir tráfico real, recorre la lista de seguridad y configura los respaldos.
Usar un bucket o una base de datos alojados
El archivo de Compose de arriba deja todo en un solo servidor. Cada almacén puede vivir en otro lugar; el motor solo necesita su dirección. Cambia los ajustes, quita de compose.yaml el servicio que ya no necesitas (y su línea en depends_on), y corre docker compose up -d.
Amazon S3
Quita minio, bucket, el segundo sitio del Caddyfile y el segundo nombre de DNS. Reemplaza las líneas SYPNIA_STORAGE_… por:
SYPNIA_STORAGE_BUCKET: <tu bucket>
SYPNIA_STORAGE_REGION: us-east-1
SYPNIA_STORAGE_ACCESS_KEY_ID: ${S3_ACCESS_KEY_ID}
SYPNIA_STORAGE_SECRET_ACCESS_KEY: ${S3_SECRET_ACCESS_KEY}En un servidor dentro de AWS con un rol, omite las dos líneas de llaves: el motor usa el rol. La llave o el rol necesita leer, escribir, listar y borrar en ese único bucket y en nada más.
Cloudflare R2
Igual que Amazon S3, con el endpoint de tu cuenta y la región auto:
SYPNIA_STORAGE_BUCKET: <tu bucket>
SYPNIA_STORAGE_REGION: auto
SYPNIA_STORAGE_ENDPOINT: https://<account id>.r2.cloudflarestorage.com
SYPNIA_STORAGE_ACCESS_KEY_ID: ${R2_ACCESS_KEY_ID}
SYPNIA_STORAGE_SECRET_ACCESS_KEY: ${R2_SECRET_ACCESS_KEY}Dejar que los navegadores lean grabaciones de un bucket alojado
La Consola reproduce una grabación trayendo sus fragmentos del bucket, en tu navegador, con enlaces firmados. Un bucket alojado lo rechaza hasta que permitas leer a la dirección de tu motor. MinIO no necesita nada: le responde a cualquier origen.
{
"CORSRules": [
{
"AllowedOrigins": ["https://sypnia.example.com"],
"AllowedMethods": ["GET"],
"AllowedHeaders": ["*"],
"MaxAgeSeconds": 3600
}
]
}aws s3api put-bucket-cors --bucket <tu bucket> --cors-configuration file://cors.jsonPara Cloudflare R2, agrega la misma regla en la configuración del bucket, o corre el mismo comando con --endpoint-url https://<account id>.r2.cloudflarestorage.com. El bucket sigue siendo privado: la regla deja que un navegador use un enlace firmado, no deja que nadie lea sin uno.
Un Postgres alojado
Quita db y su volumen, y pon la cadena de conexión. Agrega ?sslmode=require, porque la base de datos ya no está en la misma máquina.
SYPNIA_DATABASE_URL: ${DATABASE_URL}| Proveedor | Qué cadena de conexión |
|---|---|
| Supabase | La de modo sesión, en el puerto 5432. El motor mantiene unas pocas conexiones abiertas y corre transacciones de varias sentencias. |
| Neon | La directa, no la agrupada (pooled). |
| Amazon RDS, o cualquier otro Postgres 15 o posterior | La dirección de la propia instancia. |
Dale a Sypnia una base de datos propia. No compartas la que usa tu app: el trabajo del motor competiría con el de tu app por memoria y conexiones.
El día a día
| Para | Corre |
|---|---|
| Leer el log del motor | docker compose logs -f sypnia |
| Aplicar un ajuste cambiado | Edita compose.yaml o .env, y luego docker compose up -d. La configuración se lee al arrancar. |
| Comprobar todo otra vez | docker compose exec sypnia sypnia doctor |
| Actualizar el motor | docker compose pull sypnia && docker compose up -d sypnia. Lee antes Actualizaciones, respaldos y retención. |
| Detenerlo, conservando los datos | docker compose down |
| Que arranque con el servidor | Nada: restart: unless-stopped lo hace, siempre que Docker mismo arranque con el servidor. |
La detención es limpia: con docker compose down el motor termina las peticiones en curso, hasta por 20 segundos, y el worker termina su paso actual. Compose espera 10 segundos por defecto antes de matar un contenedor, así que agrega stop_grace_period: 30s al servicio sypnia si quieres los 20 completos. Un worker que muere no pierde nada en ningún caso: el procesamiento se puede repetir sin riesgo.
Eliminar todo
docker compose down -vDespués borra la carpeta con .env, los dos registros DNS y, si usaste un bucket o una base de datos alojados, también esos.
Cuando algo falla
| Lo que ves | Por qué | Qué hacer |
|---|---|---|
sypnia se reinicia en bucle; su log nombra un ajuste y termina con código de salida 3 | Falta un ajuste obligatorio o no es válido. | Corrige la línea que nombra en compose.yaml o .env. |
curl reporta un error de certificado | Caddy no pudo conseguir un certificado: el nombre no apunta a este servidor, o los puertos 80 y 443 están cerrados. | docker compose logs caddy dice cuál. Corrige el DNS o el firewall, y luego docker compose restart caddy. |
doctor dice address FAIL | El motor no llega a su propia dirección pública. | Revisa que SYPNIA_DOMAIN sea el nombre que está en el DNS y que el servidor lo pueda resolver. |
doctor dice storage FAIL … presign | SYPNIA_STORAGE_PUBLIC_ENDPOINT está mal o no se alcanza. | Tiene que ser la dirección HTTPS del almacenamiento tal como la alcanza un navegador. |
Una grabación no se reproduce y la consola del navegador muestra un 403 del almacenamiento | El proxy cambió el encabezado Host, o el reloj del almacenamiento está corrido. | Pasa Host sin cambios. Revisa el reloj del servidor. |
| Una grabación no se reproduce y la consola del navegador muestra un error de CORS | Un bucket alojado sin la regla. | Agrega la regla. |
Todos los visitantes reciben 429 a la vez | SYPNIA_TRUSTED_PROXY_HOPS está en 0 detrás de un proxy. | Ponlo en el número de proxies que hay delante del motor. |
| El disco se llena | Las grabaciones son la mayor parte de lo que guarda el motor. | Baja SYPNIA_RETENTION_REPLAYS_DAYS o SYPNIA_REPLAY_SAMPLE_RATE. Ver Estructura del almacenamiento. |
Sigue con esto
- Qué cerrar antes del tráfico real.
-
Actualizaciones, respaldos y retención
Respalda la base de datos antes de depender de ella. - Qué muestra la página integrada, y cómo protegerla.
- Conecta un modelo para tener la frase en palabras simples.