Docs

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.

Aplica a Motor Al lanzar

Ver como Markdown
En esta página
  1. Qué corre
  2. Desplegar
  3. Apunta dos nombres al servidor
  4. Escribe los secretos
  5. Escribe el archivo de Compose
  6. Escribe el archivo de Caddy
  7. Arráncalo
  8. Comprueba su salud
  9. Corre el doctor
  10. Crea el primer proyecto
  11. Crea una llave para cada app adicional, y un token para leer
  12. Envía desde tu app y mira cómo llega
  13. Usar un bucket o una base de datos alojados
  14. Amazon S3
  15. Cloudflare R2
  16. Dejar que los navegadores lean grabaciones de un bucket alojado
  17. Un Postgres alojado
  18. El día a día
  19. Eliminar todo
  20. Cuando algo falla
  21. 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

ServicioImagenQué haceSe alcanza desde fuera
sypniaghcr.io/sypnia/sypnia:1El motor completo en un proceso: sypnia serve con el rol all.Solo a través de caddy
dbpostgres:16La base de datos.No
miniominio/minioEl 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
bucketminio/mcCrea el bucket una vez y termina.No
caddycaddy:2HTTPS 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

  1. Apunta dos nombres al servidor

    En tu proveedor de DNS, crea dos registros A con la dirección del servidor:

    NombrePara
    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.com
    Deberías ver
    La dirección del servidor, dos veces.
  2. 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 .env
    Deberías ver
    Un archivo .env con 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.
  3. 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_URL es la dirección pública con HTTPS. Queda escrita en los enlaces, y es donde vive la Consola.
    • SYPNIA_TRUSTED_PROXY_HOPS es 1 porque hay un proxy, Caddy, delante del motor. Con 0 todos los visitantes compartirían un solo límite de peticiones: la dirección de Caddy.
    • SYPNIA_STORAGE_PUBLIC_ENDPOINT es la dirección que usan los navegadores para el almacenamiento. El motor sigue usando http://minio:9000, dentro de la red de Compose.

    SYPNIA_AUTO_MIGRATE está en true para que el motor cree y actualice sus tablas al arrancar. Es lo correcto para un solo proceso. Si más adelante corres varios, ponlo en false y corre sypnia migrate como un paso de tu despliegue.

  4. 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 Host sin cambios al almacenamiento, o los enlaces firmados dejan de coincidir.

  5. Arráncalo

    Terminal
    docker compose up -d
    docker compose ps
    Deberías ver
    sypnia, db, minio y caddy con el estado running. bucket no aparece en la lista: creó el bucket y terminó.
  6. Comprueba su salud

    Terminal
    curl -i https://sypnia.example.com/healthz
    Deberías ver
    HTTP/2 200. La primera vez, dale a Caddy hasta un minuto para conseguir los certificados. /healthz responde 200 cuando 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 hace sypnia doctor, en el paso siguiente.
  7. Corre el doctor

    Terminal
    docker compose exec sypnia sypnia doctor --skip ai
    Deberías ver
    Text
    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 passed

    Una línea que dice FAIL nombra el ajuste que hay que cambiar. La revisión de IA se omite porque todavía no hay un modelo conectado.

  8. Crea el primer proyecto

    Terminal
    docker compose exec sypnia sypnia project create --name Shop
    Deberías ver
    Text
    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,replay

    El 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.

  9. 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 ver
    Text
    key_8b5n2m7v4c1x  spk_a3c9e1f7b5d2084c6e0a9f3b7d1c5e82  Checkout API

    Luego 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,replay
    Deberías ver
    Una línea que empieza por sps_. Se muestra una sola vez: cópiala ahora. Es un secreto.
  10. 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/console y pega tu token de API.

    Deberías ver
    En 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:

YAML
      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:

YAML
      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.

cors.json
{
  "CORSRules": [
    {
      "AllowedOrigins": ["https://sypnia.example.com"],
      "AllowedMethods": ["GET"],
      "AllowedHeaders": ["*"],
      "MaxAgeSeconds": 3600
    }
  ]
}
Terminal
aws s3api put-bucket-cors --bucket <tu bucket> --cors-configuration file://cors.json

Para 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.

YAML
      SYPNIA_DATABASE_URL: ${DATABASE_URL}
ProveedorQué cadena de conexión
SupabaseLa de modo sesión, en el puerto 5432. El motor mantiene unas pocas conexiones abiertas y corre transacciones de varias sentencias.
NeonLa directa, no la agrupada (pooled).
Amazon RDS, o cualquier otro Postgres 15 o posteriorLa 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

ParaCorre
Leer el log del motordocker compose logs -f sypnia
Aplicar un ajuste cambiadoEdita compose.yaml o .env, y luego docker compose up -d. La configuración se lee al arrancar.
Comprobar todo otra vezdocker compose exec sypnia sypnia doctor
Actualizar el motordocker compose pull sypnia && docker compose up -d sypnia. Lee antes Actualizaciones, respaldos y retención.
Detenerlo, conservando los datosdocker compose down
Que arranque con el servidorNada: 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

Terminal
docker compose down -v

Despué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 vesPor quéQué hacer
sypnia se reinicia en bucle; su log nombra un ajuste y termina con código de salida 3Falta un ajuste obligatorio o no es válido.Corrige la línea que nombra en compose.yaml o .env.
curl reporta un error de certificadoCaddy 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 FAILEl 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 … presignSYPNIA_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 almacenamientoEl 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 CORSUn bucket alojado sin la regla.Agrega la regla.
Todos los visitantes reciben 429 a la vezSYPNIA_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 llenaLas 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

Secciones

Empieza aquíQué es Sypnia, cómo funciona, qué es código abierto y qué es la nube de pago, y las dos maneras de recibir tu primer problema en palabras claras.ConceptosLas diez ideas de las que está hecho Sypnia, cada una definida con precisión, desde un proyecto y sus llaves hasta los problemas, las trazas y las alertas.SDKCómo envía tu app los datos a Sypnia. Un SDK para el navegador, uno para Node, uno para Next.js, y la entrada de OpenTelemetry para cualquier otro backend.El agenteCómo analiza Sypnia un problema, qué escribe, qué le envía a un modelo y qué nunca hace.MCP y skillsConecta tu agente de código a Sypnia para que pregunte qué está fallando en producción, lea lo que necesita para arreglarlo y configure Sypnia por ti.Referencia de la APILa API HTTP de Sypnia: una sola API para el motor de código abierto y para Sypnia Cloud, con cada endpoint, parámetro, respuesta y error.Referencia de la CLIEl comando sypnia: cómo instalarlo, qué variables lee, qué significan sus códigos de salida y dónde está documentado cada comando.Alojamiento propioQué corres cuando alojas tú mismo el motor de Sypnia, qué necesitas, cuánto cuesta y qué no tienes frente a Sypnia Cloud.Cómo está construido el motorTodo el motor de Sypnia en una página, desde un clic en tu app hasta la frase que lee tu agente de código, con las reglas de diseño y el código que las sostiene.Sypnia CloudCómo funciona el servicio pago, desde las organizaciones y los roles hasta los planes, los límites, la facturación, dónde viven tus datos, la GitHub App y el soporte.Privacidad y seguridadQué recoge Sypnia de tu app y de sus usuarios, qué no recoge nunca, cómo funciona el enmascarado, cómo eliminar datos y cómo se protege el servicio.LicenciasQué licencia cubre cada parte de Sypnia, qué puedes hacer con ella, cómo se puede usar el nombre, y los términos de una contribución.GuíasRecetas paso a paso para las formas comunes de usar Sypnia, desde apps hechas con constructores de IA y Next.js en Vercel hasta Supabase, source maps en CI, correos de alerta desde tu propio motor, y venir desde Sentry.ReferenciaLas páginas donde se consulta, desde el esquema de eventos y el glosario hasta lo planeado, el registro de cambios y las preguntas frecuentes.
↑↓ para moverte↵ para abrirEsc para cerrar