# 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: el motor de Sypnia (código abierto, en tu propia infraestructura). Estado: al lanzar.  
Fuente: https://docs.sypnia.com/es/self-hosting/deploy-docker/

Para agentes: Cómo desplegar el motor de Sypnia con alojamiento propio en un servidor con Docker Compose: el compose.yaml completo (motor, Postgres 16, MinIO, Caddy para HTTPS), el archivo .env, la comprobación de salud, sypnia doctor, el primer proyecto, la llave de ingesta y el token de API con la CLI, variantes con Amazon S3, Cloudflare R2, Supabase o Neon, la regla CORS del bucket, comandos del día a día, eliminación y solución de fallas.

**\[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](https://docs.sypnia.com/es/start/quickstart-self-host), que es más corto; para AWS sin servidor, [Desplegar en AWS](https://docs.sypnia.com/es/self-hosting/deploy-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](https://docs.sypnia.com/es/self-hosting/scaling-and-cost)); dos nombres de DNS que apunten a él; `openssl`; unos 30 minutos.

> **Nota: Nombres planeados**
>
> El motor todavía no está publicado. La imagen `ghcr.io/sypnia/sypnia:1` es la planeada. El archivo de abajo usa los mismos nombres de servicio que el inicio rápido, así que lo que aprendiste ahí sigue valiendo.

## 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](#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:

| Nombre                       | Para                                                              |
| ---------------------------- | ----------------------------------------------------------------- |
| `sypnia.example.com`         | El motor: los SDK, la API, el servidor MCP, la Consola            |
| `storage.sypnia.example.com` | El almacenamiento: enlaces de grabaciones y subida de source maps |

```bash
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:

```bash
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`

```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](https://docs.sypnia.com/es/self-hosting/configuration). 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](https://docs.sypnia.com/es/self-hosting/scaling-and-cost#de-un-proceso-a-varios), ponlo en `false` y corre `sypnia migrate` como un paso de tu despliegue.

### 4. Escribe el archivo de Caddy

`Caddyfile`

```text
{$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

```bash
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

```bash
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

```bash
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

```bash
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:

```bash
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:

```bash
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`

```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](https://docs.sypnia.com/es/start/your-first-problem) te lleva a provocar uno a propósito.

Antes de recibir tráfico real, recorre la [lista de seguridad](https://docs.sypnia.com/es/self-hosting/security-checklist) y configura los [respaldos](https://docs.sypnia.com/es/self-hosting/upgrades-backups-retention).

## 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`

```json
{
  "CORSRules": [
    {
      "AllowedOrigins": ["https://sypnia.example.com"],
      "AllowedMethods": ["GET"],
      "AllowedHeaders": ["*"],
      "MaxAgeSeconds": 3600
    }
  ]
}
```

```bash
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}
```

| 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](https://docs.sypnia.com/es/self-hosting/upgrades-backups-retention). |
| 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

```bash
docker compose down -v
```

> **Advertencia**
>
> `-v` borra los volúmenes: la base de datos, el bucket y los certificados. Nada los puede recuperar. Sin `-v` los datos se quedan en el servidor para el próximo `docker compose up -d`.

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 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](#dejar-que-los-navegadores-lean-grabaciones-de-un-bucket-alojado).                                                                             |
| 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](https://docs.sypnia.com/es/self-hosting/storage-layout). |

## Sigue con esto
