Desplegar en AWS
Despliega el motor de Sypnia en tu propia cuenta de AWS con una sola plantilla de CloudFormation, compruébalo, crea el primer proyecto, apúntale un dominio, actualízalo y elimínalo.
En esta página
- Qué crea la plantilla
- Parámetros
- Desplegar
- Instala el comando sypnia en tu máquina
- Elige la región y crea el token raíz
- Descarga la plantilla
- Despliega el stack
- Carga la configuración del motor en tu terminal
- Crea las tablas
- Comprueba el despliegue
- Crea el primer proyecto y un token
- Envía desde tu app y mira cómo llega
- Apuntarle un dominio
- Pide un certificado en us-east-1
- Demuestra que el dominio es tuyo
- Dale el dominio al stack
- Apunta el registro DNS al stack
- Comprueba
- Cambiar un ajuste
- Actualizar el motor
- Lee qué cambió
- Actualiza el comando y la plantilla
- Actualiza primero las tablas
- Despliega la plantilla nueva
- Comprueba la versión que responde
- Eliminar todo
- Anota los nombres y elimina el stack
- Elimina el bucket y todo lo que contiene
- Elimina la instantánea final de la base de datos
- Quita lo que creaste a mano
- Cuando algo falla
- Sigue con esto
Motor Esta página es para quien despliega el motor de código abierto en su propia cuenta de AWS. No aplica a Sypnia Cloud, que es esta misma forma corrida por nosotros. Si no usas AWS, sigue Desplegar con Docker.
Al final tendrás: el motor respondiendo en una dirección HTTPS de tu cuenta de AWS, su bucket y su base de datos, un primer proyecto con una llave de ingesta y un token de API, y sypnia doctor en verde.
Necesitas: una cuenta de AWS y la AWS CLI versión 2, con una sesión que pueda crear funciones, roles, un bucket, una cola y una distribución de CloudFront; jq y openssl; unos 30 minutos, la mitad de espera.
Qué crea la plantilla
Una sola plantilla de CloudFormation, sypnia-aws.yaml, crea todo en un stack. El mismo binario sypnia corre como tres funciones; cada una es el motor con un rol.
| # | Recurso | Qué hace | Valor por defecto de la plantilla |
|---|---|---|---|
| 1 | Una distribución de CloudFront | La única dirección HTTPS del motor. Envía /v1/ingest/*, /v1/otlp/* y /v1/sdk.js a la función de ingesta y todo lo demás a la función de la API. Acepta tu propio dominio si le das uno. | Sin caché, salvo /v1/sdk.js |
| 2 | Función sypnia-ingest | SYPNIA_ROLE=ingest. Revisa cada lote y lo pone en la cola; escribe los fragmentos de grabación y las capturas de página en el bucket. | 256 MB, 10 s, máximo 40 copias a la vez |
| 3 | Función sypnia-api | SYPNIA_ROLE=api. La API, el servidor MCP y la Consola. | 512 MB, 30 s, máximo 20 copias |
| 4 | Una cola, y una segunda para los mensajes que fallaron cinco veces | Guarda los lotes hasta 4 días, hasta que el worker los escribe. Es el búfer que una función no puede mantener en memoria. | Cola estándar |
| 5 | Función sypnia-worker, y una programación que la despierta cada minuto | SYPNIA_ROLE=worker. Escribe segmentos, encuentra problemas, cuenta, corre las comprobaciones de disponibilidad, el agente, las alertas, los webhooks y la retención. La despierta la cola, y la programación cuando no hay tráfico. | 1.024 MB, 15 min, máximo 2 copias |
| 6 | Un bucket de S3 | Eventos crudos, grabaciones, capturas, source maps. Privado, cifrado, con el acceso público bloqueado, una regla que deja a tu dirección leer grabaciones desde un navegador, y una regla de ciclo de vida que borra las subidas sin terminar a los 7 días. | Se conserva cuando se elimina el stack |
| 7 | Un Postgres en RDS, solo si lo pides | La base de datos. Postgres 16, 20 GB, cifrado, respaldos diarios guardados 7 días, con la contraseña generada y guardada en Secrets Manager. | db.t4g.micro; se toma una instantánea final cuando se elimina el stack |
| Roles, y un grupo de logs por función | Cada función solo puede tocar el bucket y la cola de este stack: ingest puede enviar a la cola y escribir objetos, api puede leer objetos y firmar enlaces, worker puede leer y escribir en el bucket. Los logs se guardan 30 días. | ||
| Dos alarmas | Una cuando un mensaje cae en la segunda cola, otra cuando el worker sigue fallando. Se ven en CloudWatch; apúntalas a una notificación tuya si quieres que te avisen. |
No operas la cola ni la programación: la plantilla las crea y AWS las corre. Por qué las funciones necesitan una cola, qué despierta a cada función y qué cambia en los tiempos, está en Formas de despliegue y Flujo de datos.
Parámetros
| Parámetro | Por defecto | Qué configura |
|---|---|---|
RootToken | Obligatorio | El token raíz, SYPNIA_ROOT_TOKEN. Al menos 32 caracteres. |
CreateDatabase | true | true crea el Postgres en RDS. false usa DatabaseUrl. |
DatabaseUrl | Vacío | Tu propio Postgres, como SYPNIA_DATABASE_URL. Obligatorio cuando CreateDatabase es false. Termínalo con ?sslmode=require. |
DatabaseInstanceClass | db.t4g.micro | El tamaño de la base de datos que crea la plantilla. |
DomainName | Vacío | Tu propio dominio para el motor, como sypnia.example.com. Vacío usa la dirección que CloudFront le da al stack. |
CertificateArn | Vacío | El certificado de DomainName, de AWS Certificate Manager en us-east-1. Obligatorio con DomainName. |
AiProvider, AiApiKey, AiModel | none, vacío, vacío | SYPNIA_AI_PROVIDER, SYPNIA_AI_API_KEY, SYPNIA_AI_MODEL. El agente está apagado mientras el proveedor sea none. |
AlertWebhookUrl, AlertWebhookSecret | Vacío | SYPNIA_ALERT_WEBHOOK_URL, SYPNIA_ALERT_WEBHOOK_SECRET. Vacío no envía nada; las alertas igual quedan registradas. |
Version | La versión de la propia plantilla | Qué versión del motor corren las funciones. |
CodeBucket | sypnia-releases-<region> | El bucket del que se lee el paquete de las funciones. Cámbialo solo si tu región no tiene uno (ver Cuando algo falla). |
La plantilla configura por su cuenta estos ajustes, y no deberías cambiarlos: SYPNIA_BASE_URL, SYPNIA_ROLE, SYPNIA_STORAGE_BUCKET, SYPNIA_STORAGE_REGION, SYPNIA_TRUSTED_PROXY_HOPS y SYPNIA_DATABASE_MAX_CONNECTIONS. Cualquier otro ajuste de la referencia de configuración queda en su valor por defecto hasta que lo cambies.
Desplegar
Despliega el stack
Con una base de datos creada por la plantilla:
Terminal aws cloudformation deploy \ --template-file sypnia-aws.yaml \ --stack-name sypnia \ --capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND \ --parameter-overrides \ RootToken="$(cat sypnia-root-token.txt)" \ CreateDatabase=trueCon tu propio Postgres, reemplaza la última línea por estas dos:
Terminal CreateDatabase=false \ DatabaseUrl='postgres://sypnia:<password>@<host>:5432/sypnia?sslmode=require'Deberías verText Waiting for changeset to be created.. Waiting for stack create/update to complete Successfully created/updated stack - sypniaUnos 15 minutos cuando la plantilla crea la base de datos, unos 5 cuando traes la tuya. La base de datos y la dirección de CloudFront son lo que más tarda.
Carga la configuración del motor en tu terminal
Las funciones guardan la configuración del motor como variables de entorno. Léelas del worker, para que los comandos que corras después usen exactamente la misma base de datos y el mismo bucket.
Terminal eval "$(aws lambda get-function-configuration --function-name sypnia-worker \ --query 'Environment.Variables' --output json \ | jq -r 'to_entries[] | select(.key | startswith("SYPNIA_")) | "export \(.key)=\(.value | @sh)"')" echo "$SYPNIA_BASE_URL"Deberías verLa dirección de tu motor, comohttps://d2k4x7example.cloudfront.net. Tu terminal ahora guarda secretos, entre ellos el token raíz: ciérrala cuando termines.Comprueba el despliegue
Terminal curl -i "$SYPNIA_BASE_URL/healthz" sypnia doctor --skip aiDeberías verHTTP/2 200del primer comando. Del segundo:Text config ok 12 settings read, 0 unknown database ok postgres 16.4, schema 12 (up to date), 41 ms storage ok s3://sypnia-bucket-1a2b3c4d5e6f: put, get, delete, presign address ok https://d2k4x7example.cloudfront.net/healthz answered 200 webhook skip SYPNIA_ALERT_WEBHOOK_URL is not set (alerts are recorded only) clock ok 0.3 s from the database's clock all checks passedsypnia doctorcorre en tu máquina con tu propia sesión de AWS. Prueba la configuración, la base de datos y el bucket. Que las funciones mismas llegan a ellos lo pruebanhealthzy los dos pasos siguientes.Crea el primer proyecto y un token
Terminal 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,replayTerminal 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.Envía desde tu app y mira cómo llega
Apunta el SDK a tu motor con
endpoint, como en el inicio rápido:init({ project: 'spk_…', endpoint: '<tu URL base>' }). Abre tu app, haz clic por ahí, y luego:Terminal SYPNIA_API_TOKEN=<tu token sps_> sypnia problems --environment developmentDeberías verEn menos de 2 minutos desde un primer error, un problema. Las sesiones y los números llegan en menos de 10 minutos. La Consola está en<tu URL base>/console.
Antes de recibir tráfico real, apunta tu dominio al motor, para que la dirección en tu app sea la definitiva, y recorre la lista de seguridad.
Apuntarle un dominio
Al final tendrás: el motor en https://sypnia.example.com. Hazlo antes de publicar el SDK en tu app. La dirección de CloudFront sigue funcionando después, así que nada de lo que ya le envía se rompe.
Pide un certificado en us-east-1
CloudFront solo acepta certificados de
us-east-1, sea cual sea la región de tu stack.Terminal aws acm request-certificate --region us-east-1 \ --domain-name sypnia.example.com --validation-method DNS \ --query CertificateArn --output textDeberías verUna dirección que empieza porarn:aws:acm:us-east-1:. Guárdala para los pasos siguientes.Demuestra que el dominio es tuyo
Terminal aws acm describe-certificate --region us-east-1 --certificate-arn <el ARN> \ --query "Certificate.DomainValidationOptions[0].ResourceRecord"Crea en tu proveedor de DNS el registro
CNAMEque imprime, y espera:Terminal aws acm wait certificate-validated --region us-east-1 --certificate-arn <el ARN>Deberías verEl comando termina sin mensaje, normalmente a los pocos minutos de existir el registro.Dale el dominio al stack
Los parámetros que no nombras conservan su valor.
Terminal aws cloudformation deploy \ --template-file sypnia-aws.yaml \ --stack-name sypnia \ --capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND \ --parameter-overrides DomainName=sypnia.example.com CertificateArn=<el ARN>Deberías verSuccessfully created/updated stack - sypnia, después de unos 5 minutos.Apunta el registro DNS al stack
Terminal aws cloudformation describe-stacks --stack-name sypnia \ --query "Stacks[0].Outputs[?OutputKey=='DistributionDomain'].OutputValue" --output textCrea un registro
CNAMEdesypnia.example.comhacia el nombre que imprime. Para un dominio sin subdominio, usa el registro de alias de tu proveedor de DNS.
Cambiar un ajuste
La configuración se lee cuando una función arranca, y un despliegue reinicia las funciones.
-
Un ajuste que tiene parámetro: despliega otra vez con el valor nuevo. Por ejemplo, para conectar un modelo:
Terminal aws cloudformation deploy \ --template-file sypnia-aws.yaml --stack-name sypnia \ --capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND \ --parameter-overrides AiProvider=openrouter AiApiKey=<tu llave> AiModel=<model>Luego vuelve a cargar la configuración y corre
sypnia doctor --only ai. -
Cualquier otro ajuste: las tres funciones comparten una lista de variables de entorno cerca del inicio de la plantilla, bajo
Globals. Agrega ahí la líneaSYPNIA_…del ajuste, conserva el archivo editado y despliégalo. Mantén tus cambios cuando descargues una plantilla más nueva.
Actualizar el motor
Al final tendrás: las tres funciones en la versión nueva, sin detener la ingesta. Las migraciones solo agregan, así que las funciones viejas siguen funcionando contra las tablas nuevas mientras el stack se actualiza.
Lee qué cambió
El registro de cambios dice qué cambia cada versión y si te pide algo.
Para volver atrás, despliega otra vez la plantilla anterior. La base de datos no necesita nada: un motor más viejo funciona contra un esquema más nuevo. Más sobre esto en Actualizaciones, respaldos y retención.
Eliminar todo
Eliminar el stack quita las funciones, la cola, la programación, la dirección, los roles y los logs. A propósito deja tus datos: el bucket se conserva, y la base de datos que creó la plantilla se elimina después de una instantánea final.
Anota los nombres y elimina el stack
Terminal aws cloudformation describe-stacks --stack-name sypnia --query "Stacks[0].Outputs" --output table aws cloudformation delete-stack --stack-name sypnia aws cloudformation wait stack-delete-complete --stack-name sypniaDeberías verLa tabla muestraBucketNamey, si la plantilla creó la base de datos,DatabaseIdentifier. El último comando termina sin mensaje después de unos 10 minutos.Elimina la instantánea final de la base de datos
Solo si la plantilla creó la base de datos.
Terminal aws rds describe-db-snapshots --db-instance-identifier <DatabaseIdentifier> \ --query "DBSnapshots[].DBSnapshotIdentifier" --output text aws rds delete-db-snapshot --db-snapshot-identifier <el nombre impreso>
Después de esto no queda nada de Sypnia en la cuenta y no se cobra nada.
Cuando algo falla
| Lo que ves | Por qué | Qué hacer |
|---|---|---|
Requires capabilities : [CAPABILITY_AUTO_EXPAND] | La plantilla usa una transformación de CloudFormation. | Pasa las dos capacidades, como en los comandos de arriba. |
| El stack falla en una función con «S3 bucket does not exist» o «Access Denied» | El paquete de las funciones no está publicado en tu región. | Descarga sypnia-lambda-arm64.zip de la misma versión, súbelo a un bucket tuyo en esa región bajo <Version>/sypnia-lambda-arm64.zip, y despliega con CodeBucket=<tu bucket>. |
| El stack falla con «The specified SSL certificate doesn’t exist, isn’t in us-east-1 region» | El certificado se pidió en otra región. | Pídelo otra vez con --region us-east-1. |
healthz responde 502 o 503 justo después del primer despliegue | Las tablas todavía no existen. El motor se niega a arrancar contra un esquema más viejo que él. | Corre sypnia migrate. Para ver el motivo: aws logs tail /aws/lambda/sypnia-api --since 10m. |
sypnia doctor dice database FAIL desde tu máquina, con tu propio Postgres | Tu base de datos no acepta conexiones desde internet. Las funciones están fuera de tu red, igual que tu máquina. | Permite la conexión con TLS, o usa una base de datos a la que las funciones lleguen. |
sypnia doctor pasa y nunca aparece un problema | El worker no está corriendo. | aws logs tail /aws/lambda/sypnia-worker --since 10m. Una línea que nombra un ajuste faltante, o un error de base de datos, dice qué arreglar. |
La API responde 503 con Retry-After bajo carga | La base de datos no tiene conexiones libres. | Ver Escalado y costo. |
Los navegadores reciben 403 origin_not_allowed | El proyecto tiene una lista de orígenes permitidos, y el de tu app no está. | Agrégalo con PATCH /v1/projects/{project_ref}. Ver la referencia de la API. |
| Llegan eventos y la Consola no reproduce una grabación | Tu navegador lee la grabación directo del bucket, con un enlace de corta duración. Un proxy o una extensión que bloquea amazonaws.com lo rompe. | Prueba con otro perfil del navegador. Ver La Consola. |
Sigue con esto
- Qué cerrar antes del tráfico real.
-
Actualizaciones, respaldos y retención
Qué respaldar, y cuánto tiempo guardar los datos. - Cuánto cuesta este stack, con la aritmética.
- Recibe un correo cuando algo se rompe.