Deploy on AWS
Deploy the Sypnia engine on your own AWS account with one CloudFormation template, check it, create the first project, point a domain at it, update it, and remove it.
On this page
- What the template creates
- Parameters
- Deploy
- Install the sypnia command on your machine
- Choose the region and make the root token
- Download the template
- Deploy the stack
- Load the engine's settings into your shell
- Create the tables
- Check the deployment
- Create the first project and a token
- Send from your app and see it arrive
- Point a domain at it
- Ask for a certificate in us-east-1
- Prove the domain is yours
- Give the domain to the stack
- Point the DNS record at the stack
- Check
- Change a setting
- Update the engine
- Read what changed
- Update the command and the template
- Update the tables first
- Deploy the new template
- Check the version that answers
- Remove everything
- Note the names, then delete the stack
- Delete the bucket and everything in it
- Delete the database's final snapshot
- Remove what you created by hand
- Troubleshooting
- Next
Engine This page is for whoever deploys the open-source engine on their own AWS account. It does not apply to Sypnia Cloud, which is this same shape run by us. If you do not use AWS, follow Deploy with Docker.
At the end you will have: the engine answering at an HTTPS address of your AWS account, its bucket and its database, a first project with an ingest key and an API token, and sypnia doctor passing.
You need: an AWS account and the AWS CLI version 2, signed in as someone who can create functions, roles, a bucket, a queue and a CloudFront distribution; jq and openssl; about 30 minutes, half of it waiting.
What the template creates
One CloudFormation template, sypnia-aws.yaml, creates everything in one stack. The same sypnia binary runs as three functions; each one is the engine with one role.
| # | Resource | What it does | Template default |
|---|---|---|---|
| 1 | A CloudFront distribution | The engine’s one HTTPS address. Sends /v1/ingest/*, /v1/otlp/* and /v1/sdk.js to the ingest function and everything else to the API function. Takes your own domain if you give one. | No caching, except /v1/sdk.js |
| 2 | Function sypnia-ingest | SYPNIA_ROLE=ingest. Checks each batch and puts it in the queue; writes replay chunks and page snapshots to the bucket. | 256 MB, 10 s, at most 40 copies at once |
| 3 | Function sypnia-api | SYPNIA_ROLE=api. The API, the MCP server and the Console. | 512 MB, 30 s, at most 20 copies |
| 4 | A queue, and a second one for messages that failed five times | Holds batches for up to 4 days until the worker writes them. It is the buffer a function cannot keep in memory. | Standard queue |
| 5 | Function sypnia-worker, and a schedule that wakes it every minute | SYPNIA_ROLE=worker. Writes segments, finds problems, counts, runs uptime checks, the agent, alerts, webhooks and retention. Woken by the queue, and by the schedule when there is no traffic. | 1,024 MB, 15 min, at most 2 copies |
| 6 | An S3 bucket | Raw events, replays, snapshots, source maps. Private, encrypted, public access blocked, a rule that lets your address read replays from a browser, and one lifecycle rule that removes unfinished uploads after 7 days. | Kept when the stack is deleted |
| 7 | An RDS Postgres, only if you ask for it | The database. Postgres 16, 20 GB, encrypted, daily backups kept 7 days, its password generated and stored in Secrets Manager. | db.t4g.micro; a final snapshot is taken when the stack is deleted |
| Roles, and a log group per function | Each function may touch only this stack’s bucket and queue: ingest may send to the queue and put objects, api may read objects and sign links, worker may read and write the bucket. Logs are kept 30 days. | ||
| Two alarms | One when a message lands in the second queue, one when the worker keeps failing. They show in CloudWatch; point them at a notification of yours if you want to be told. |
You do not operate the queue or the schedule: the template creates them and AWS runs them. Why functions need a queue, what each function is woken by, and what it changes in the timing, is in Deployment shapes and Data flow.
Parameters
| Parameter | Default | What it sets |
|---|---|---|
RootToken | Required | The root token, SYPNIA_ROOT_TOKEN. At least 32 characters. |
CreateDatabase | true | true creates the RDS Postgres. false uses DatabaseUrl. |
DatabaseUrl | Empty | Your own Postgres, as SYPNIA_DATABASE_URL. Required when CreateDatabase is false. End it with ?sslmode=require. |
DatabaseInstanceClass | db.t4g.micro | The size of the database the template creates. |
DomainName | Empty | Your own domain for the engine, such as sypnia.example.com. Empty uses the address CloudFront gives the stack. |
CertificateArn | Empty | The certificate for DomainName, from AWS Certificate Manager in us-east-1. Required with DomainName. |
AiProvider, AiApiKey, AiModel | none, empty, empty | SYPNIA_AI_PROVIDER, SYPNIA_AI_API_KEY, SYPNIA_AI_MODEL. The agent is off while the provider is none. |
AlertWebhookUrl, AlertWebhookSecret | Empty | SYPNIA_ALERT_WEBHOOK_URL, SYPNIA_ALERT_WEBHOOK_SECRET. Empty sends nothing; alerts are still recorded. |
Version | The template’s own version | Which release of the engine the functions run. |
CodeBucket | sypnia-releases-<region> | The bucket the function package is read from. Change it only if your region has none (see Troubleshooting). |
The template sets these settings itself, and you should not change them: SYPNIA_BASE_URL, SYPNIA_ROLE, SYPNIA_STORAGE_BUCKET, SYPNIA_STORAGE_REGION, SYPNIA_TRUSTED_PROXY_HOPS and SYPNIA_DATABASE_MAX_CONNECTIONS. Every other setting of the configuration reference has its default until you change it.
Deploy
Deploy the stack
With a database created by the template:
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=trueWith your own Postgres, replace the last line with these two:
Terminal CreateDatabase=false \ DatabaseUrl='postgres://sypnia:<password>@<host>:5432/sypnia?sslmode=require'You should seeText Waiting for changeset to be created.. Waiting for stack create/update to complete Successfully created/updated stack - sypniaAbout 15 minutes when the template creates the database, about 5 when you bring yours. The database and the CloudFront address take the longest.
Load the engine's settings into your shell
The functions hold the engine’s settings as environment variables. Read them from the worker, so the commands you run next use exactly the same database and 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"You should seeThe address of your engine, such ashttps://d2k4x7example.cloudfront.net. Your shell now holds secrets, the root token among them: close it when you finish.Check the deployment
Terminal curl -i "$SYPNIA_BASE_URL/healthz" sypnia doctor --skip aiYou should seeHTTP/2 200from the first command. From the second: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 doctorruns on your machine with your own AWS sign-in. It proves the settings, the database and the bucket. That the functions themselves can reach them is proved byhealthzand by the next two steps.Create the first project and a token
Terminal sypnia project create --name ShopYou should seeText 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,replayYou should seeA line that starts withsps_. It is shown once: copy it now.Send from your app and see it arrive
Point the SDK at your engine with
endpoint, as in the quickstart:init({ project: 'spk_…', endpoint: '<your base URL>' }). Open your app, click around, then:Terminal SYPNIA_API_TOKEN=<your sps_ token> sypnia problems --environment developmentYou should seeWithin 2 minutes of a first error, one problem. Sessions and numbers follow within 10 minutes. The Console is at<your base URL>/console.
Before real traffic, point your domain at the engine, so the address in your app is the final one, and go through the security checklist.
Point a domain at it
At the end you will have: the engine at https://sypnia.example.com. Do this before you ship the SDK in your app. The CloudFront address keeps working afterwards, so nothing that already sends to it breaks.
Ask for a certificate in us-east-1
CloudFront only takes certificates from
us-east-1, whatever region your stack is in.Terminal aws acm request-certificate --region us-east-1 \ --domain-name sypnia.example.com --validation-method DNS \ --query CertificateArn --output textYou should seeAn address that starts witharn:aws:acm:us-east-1:. Keep it for the next steps.Prove the domain is yours
Terminal aws acm describe-certificate --region us-east-1 --certificate-arn <the ARN> \ --query "Certificate.DomainValidationOptions[0].ResourceRecord"Create the
CNAMErecord it prints at your DNS provider, then wait:Terminal aws acm wait certificate-validated --region us-east-1 --certificate-arn <the ARN>You should seeThe command returns without a message, usually within a few minutes of the record existing.Give the domain to the stack
Parameters you do not name keep their value.
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=<the ARN>You should seeSuccessfully created/updated stack - sypnia, after about 5 minutes.Point the DNS record at the stack
Terminal aws cloudformation describe-stacks --stack-name sypnia \ --query "Stacks[0].Outputs[?OutputKey=='DistributionDomain'].OutputValue" --output textCreate a
CNAMErecord fromsypnia.example.comto the name it prints. For a bare domain without a subdomain, use your DNS provider’s alias record.
Change a setting
Settings are read when a function starts, and a deploy restarts the functions.
-
A setting that has a parameter: deploy again with the new value. For example, to connect a model:
Terminal aws cloudformation deploy \ --template-file sypnia-aws.yaml --stack-name sypnia \ --capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND \ --parameter-overrides AiProvider=openrouter AiApiKey=<your key> AiModel=<model>Then load the settings again and run
sypnia doctor --only ai. -
Any other setting: the three functions share one list of environment variables near the top of the template, under
Globals. Add the setting’sSYPNIA_…line there, keep the edited file, and deploy it. Keep your changes when you download a newer template.
Update the engine
At the end you will have: the three functions on the new version, without stopping ingest. Migrations only add, so the old functions keep working against the new tables while the stack updates.
Read what changed
The changelog says what each version changes and whether it asks anything of you.
To go back, deploy the previous template again. The database needs nothing: an older engine works against a newer schema. More on this in Upgrades, backups, retention.
Remove everything
Deleting the stack removes the functions, the queue, the schedule, the address, the roles and the logs. It deliberately leaves your data: the bucket is kept, and the database the template created is deleted after a final snapshot.
Note the names, then delete the 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 sypniaYou should seeThe table showsBucketNameand, if the template created the database,DatabaseIdentifier. The last command returns without a message after about 10 minutes.
After this, nothing of Sypnia is left in the account and nothing is billed.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
Requires capabilities : [CAPABILITY_AUTO_EXPAND] | The template uses a CloudFormation transform. | Pass both capabilities, as in the commands above. |
| The stack fails on a function with «S3 bucket does not exist» or «Access Denied» | The function package is not published in your region. | Download sypnia-lambda-arm64.zip from the same release, upload it to a bucket of yours in that region under <Version>/sypnia-lambda-arm64.zip, and deploy with CodeBucket=<your bucket>. |
| The stack fails with «The specified SSL certificate doesn’t exist, isn’t in us-east-1 region» | The certificate was requested in another region. | Request it again with --region us-east-1. |
healthz answers 502 or 503 right after the first deploy | The tables do not exist yet. The engine refuses to start against a schema older than itself. | Run sypnia migrate. To see the reason: aws logs tail /aws/lambda/sypnia-api --since 10m. |
sypnia doctor says database FAIL from your machine, with your own Postgres | Your database does not accept connections from the internet. The functions are outside your network, as your machine is. | Allow the connection with TLS, or use a database the functions can reach. |
sypnia doctor passes and no problem ever appears | The worker is not running. | aws logs tail /aws/lambda/sypnia-worker --since 10m. A line that names a missing setting, or a database error, says what to fix. |
The API answers 503 with Retry-After under load | The database has no free connection. | See Scaling and cost. |
Browsers get 403 origin_not_allowed | The project lists allowed origins, and your app’s is not among them. | Add it with PATCH /v1/projects/{project_ref}. See the API reference. |
| Events arrive and the Console does not play a replay | The replay is read by your browser straight from the bucket, through a short-lived link. A proxy or an extension that blocks amazonaws.com breaks it. | Try another browser profile. See The Console. |
Next
- What to close before real traffic.
- What to back up, and how long to keep data.
- What this stack costs, with the arithmetic.
- Get an e-mail when something breaks.