Deploying Tessera¶
Tessera is a single Python process. It keeps all of its state in one data folder: tessera.db (SQLite metadata),
warehouse.duckdb (the analytical store), imports/, exports/ and master.key. Three things matter wherever
you run it:
- A persistent disk for the data folder. Anything that wipes the disk on restart, sleep or rescheduling loses data.
- HTTPS in front of it, with
TESSERA_SECURE_COOKIES=trueandTESSERA_BASE_URLset to the public address. - Backups of the data folder, including
master.key(without it, stored connection passwords cannot be decrypted).
Run exactly one Tessera process per data folder. It is not designed for several replicas sharing a disk.
| Option | Good for | Effort |
|---|---|---|
| Your computer | Trying it, personal analysis | 2 minutes |
| Any server with Docker | A team on a VM you already have | 10 minutes |
| AWS | A managed, backed-up install from one template | 15 minutes |
| Cloudflare Containers | Running all of Tessera on Cloudflare, with data kept in R2 and no server to manage | 20 minutes |
| Cloudflare from a phone | The same, deployed through GitHub Actions without a computer | 30 minutes |
| Cloudflare Tunnel | Publishing a Tessera that runs on your own server, without opening ports, behind single sign-on | 20 minutes |
Sizing: 2 vCPU and 8 GB RAM serve a team of dozens with tens of gigabytes. DuckDB uses memory first and spills to disk, so give the data volume room for about twice your largest table. On a 2-vCPU machine a mixed load ran at about 160 requests per second with p95 latency near 130 ms.
Your computer¶
git clone https://github.com/vvipinthomas/tessera.git && cd tessera
python -m venv .venv && source .venv/bin/activate
pip install -e ".[s3,kafka,mqtt,iceberg,sftp,delta,mongodb]"
tessera serve # http://127.0.0.1:8710
tessera serve listens on 127.0.0.1 only. To reach it from other machines on your network, use
tessera serve --host 0.0.0.0 and put HTTPS in front before anyone signs in from elsewhere.
On Windows, use PowerShell and .venv\Scripts\Activate.ps1. Everything else is the same.
Any server with Docker¶
Works on any Linux VM (Ubuntu, Debian, Amazon Linux, RHEL), on-premises or in any cloud.
# 1. Install Docker Engine and the Compose plugin: https://docs.docker.com/engine/install/
git clone https://github.com/vvipinthomas/tessera.git && cd tessera
# 2a. HTTP on port 8710 (inside a private network only)
docker compose up -d --build
# 2b. HTTPS with an automatic Let's Encrypt certificate
# First point a DNS A record at this server and open ports 80 and 443.
TESSERA_DOMAIN=tessera.example.com \
docker compose -f docker-compose.yml -f deploy/https/docker-compose.https.yml up -d --build
# 3. Read the one-time setup code and open the site
docker compose logs tessera | grep "Setup code"
The HTTPS file adds a Caddy container that obtains and renews the certificate, removes the
direct port, and turns on secure cookies. Put TESSERA_DOMAIN=... in a .env file next to docker-compose.yml so
later commands pick it up.
Where the data is. In the tessera-data Docker volume. To keep it in a folder you choose instead, add a
docker-compose.override.yml:
services:
tessera:
volumes: !override
- /srv/tessera/data:/data
and run sudo chown -R 10001:10001 /srv/tessera/data once (the container runs as user 10001, not root).
Upgrading. git pull && docker compose up -d --build. Database changes are applied automatically at start-up.
Take a backup first.
AWS¶
The template deploy/aws/tessera-ec2.yaml creates everything in one stack:
| Resource | Why |
|---|---|
| EC2 instance (Amazon Linux 2023, Docker) | Runs Tessera and, when you give a domain, Caddy for HTTPS |
Encrypted gp3 EBS data volume mounted at /srv/tessera |
Holds the data folder. Snapshotted, not deleted, if the stack is deleted |
| Elastic IP | A stable address for your DNS record |
| Private, versioned, encrypted S3 bucket | Nightly consistent backups, kept 35 days. Retained if the stack is deleted |
| IAM role with Systems Manager | Shell access through Session Manager, so no SSH port is open |
| Security group | 443 (and 80 for the certificate) from the range you choose |
Create the stack¶
Console: CloudFormation → Create stack → Upload a template file → deploy/aws/tessera-ec2.yaml.
Or with the AWS CLI:
aws cloudformation deploy \
--stack-name tessera \
--template-file deploy/aws/tessera-ec2.yaml \
--capabilities CAPABILITY_IAM \
--parameter-overrides DomainName=tessera.example.com AllowedCidr=203.0.113.0/24 InstanceType=m7i.large DataVolumeGiB=100
aws cloudformation describe-stacks --stack-name tessera --query "Stacks[0].Outputs"
Then:
- DNS. Create an A record for your domain pointing at the
PublicIpoutput. Caddy gets the certificate on the first request after the record resolves (a minute or two). Without a domain, Tessera is athttp://<PublicIp>:8710; use that only from a trusted network. - Setup code. Connect with Session Manager (
aws ssm start-session --target <instance-id>, or EC2 → Connect → Session Manager in the console) and runsudo cat /srv/tessera/data/setup-code.txt. Setup takes about five minutes after the stack completes; progress is in/var/log/tessera-setup.log. - Open the URL, enter the code and create the admin.
Backups and restore¶
A cron job runs /usr/local/bin/tessera-backup at the hour you chose. It stops Tessera for a few seconds, writes a
checksummed archive with tessera backup --include-key, starts Tessera, and uploads the archive to
s3://<BackupBucket>/backups/. The archive contains master.key, which is why the bucket blocks public access,
requires TLS and is encrypted. Logs are in /var/log/tessera-backup.log.
To restore onto a new instance:
aws s3 cp s3://<BackupBucket>/backups/tessera-backup-<time>.tar.gz /tmp/
cd /opt/tessera && $(cat .compose-cmd) stop tessera
$(cat .compose-cmd) run --rm --no-deps -v /tmp:/restore tessera tessera restore /restore/tessera-backup-<time>.tar.gz --force
$(cat .compose-cmd) start tessera
Upgrading on AWS¶
cd /opt/tessera && sudo git fetch --tags && sudo git checkout v1.5.1 # the new tag
sudo $(cat .compose-cmd) up -d --build
Other AWS options¶
- Amazon ECS on EC2 works with the same container image if you pin the task to one instance and mount an EBS
volume (or a host path) at
/data. Run one task only. - AWS Fargate with EFS, App Runner, Lambda and Lightsail containers are not recommended. Fargate and App Runner disks are temporary; EFS is a network file system, which DuckDB and SQLite do not handle well for locking or speed; Lambda cannot keep a server running.
- Load balancer instead of Caddy: put an Application Load Balancer with an ACM certificate in front of port 8710,
set
TESSERA_SECURE_COOKIES=trueandTESSERA_BASE_URL, and set the target group health check to/api/ready. - Snapshots: you can add an Amazon Data Lifecycle Manager policy for daily EBS snapshots of the data volume as a second layer of protection.
Cloudflare¶
There are two ways to use Cloudflare:
- Run Tessera on Cloudflare with Containers, a Worker in front and data kept in R2. No server to manage. See CLOUDFLARE.md.
- Publish a Tessera that runs on your own server through a Cloudflare Tunnel, described here. Use this when the data must stay on your hardware, or when the warehouse is too big for a container's disk.
The tunnel setup:
browser ──HTTPS──▶ Cloudflare edge (TLS, WAF, optional Access SSO) ──Tunnel──▶ cloudflared ──▶ Tessera on your server
Tessera runs on any machine you have (an office server, a home lab, a VM in any cloud). The machine needs no open
inbound ports: cloudflared makes an outbound connection to Cloudflare.
1. Create the tunnel¶
- In the Cloudflare dashboard, open Zero Trust → Networks → Tunnels → Create a tunnel, choose Cloudflared,
name it
tessera, and copy the token shown in the install command. - Under Public hostnames, add
tessera.example.com(a domain on your Cloudflare account) with service type HTTP and URLtessera:8710.
2. Start Tessera with the tunnel¶
git clone https://github.com/vvipinthomas/tessera.git && cd tessera
cat > .env <<'EOF'
TUNNEL_TOKEN=<token from step 1>
TESSERA_DOMAIN=tessera.example.com
EOF
docker compose -f docker-compose.yml -f deploy/cloudflare/docker-compose.tunnel.yml up -d --build
docker compose logs tessera | grep "Setup code"
Open https://tessera.example.com. Tessera's port is not published on the host at all; only the tunnel can reach it.
3. Optional: Cloudflare Access in front¶
Access adds your identity provider's sign-in before anyone reaches Tessera's own sign-in page.
- Zero Trust → Access → Applications → Add an application → Self-hosted, domain
tessera.example.com, with a policy such as "emails ending in @example.com". - Machines also call Tessera, so add Bypass (or service-token) policies for these paths, which carry their own tokens:
/odata/*(Power BI, Excel, Tableau)/mcp(AI clients)/api/streams/*/events(HTTP push streams)/scim/v2/*(user provisioning from Entra ID or Okta)/api/auth/oidc/callbackif you also use Tessera's own SSO- If you use Tessera's built-in OpenID Connect SSO as well, people sign in twice. Many teams use Access for the network boundary and Tessera SSO for roles; both work.
4. Optional: the landing page on Cloudflare Pages¶
The marketing page can be built as one static file and hosted for free:
python scripts/build_artifact.py site/index.html
npx wrangler pages deploy site --project-name tessera-site
Backups with Cloudflare¶
Cloudflare does not hold any Tessera data. Back up the server's data folder as in Backups, for example to
Cloudflare R2 with any S3 tool: aws s3 cp backup.tar.gz s3://bucket/ --endpoint-url https://<account>.r2.cloudflarestorage.com.
Backups¶
| Method | Downtime | Command |
|---|---|---|
| Admin page | None | Admin → Operations → Download backup |
| API (scriptable) | None | curl -X POST https://tessera.example.com/api/admin/backup -H "Authorization: Bearer <admin token>" -H "x-tessera-csrf: 1" -o backup.tar.gz |
| Command line | Stop first | tessera backup --out backup.tar.gz [--include-key] |
Restore with tessera restore backup.tar.gz --force while Tessera is stopped. Archives carry a SHA-256 manifest and
restore refuses a tampered or truncated file.
Production checklist¶
- [ ] HTTPS in front,
TESSERA_SECURE_COOKIES=true,TESSERA_BASE_URLset - [ ] The data folder on a persistent, backed-up disk;
master.keystored safely (orTESSERA_MASTER_KEYfrom a secret store) - [ ] Nightly backups, and one restore tried on a spare machine
- [ ] SSO configured (Admin → Single sign-on) and the setup admin's password stored in a vault
- [ ]
TESSERA_TIMEZONEset for schedules;TESSERA_LOG_JSON=trueif you ship logs - [ ]
/metricsscraped withTESSERA_METRICS_TOKEN;/api/readyused as the health check - [ ]
TESSERA_BLOCK_PRIVATE_HTTP=trueif REST connectors must not reach your internal network - [ ] Email configured (Admin → Email) so alerts and subscriptions can be delivered
See CONFIGURATION.md for every setting.