Skip to content
Savvas Leousis edited this page Sep 26, 2026 · 1 revision

Deploy

Stonks runs on one small always-on cloud VM with Docker Compose. Traders reach it privately over Tailscale. Heavy lab runs stay on a bigger machine.

flowchart LR
  subgraph tailnet[Tailscale, private]
    L[Trader laptop]
    P[Trader phone]
  end
  subgraph vm[Cloud VM]
    C[Caddy<br/>HTTPS]
    A[api<br/>stonks serve + console]
    S[scheduler]
    V[(data volume<br/>lake, bars, state, artifacts)]
    C --> A
    A --- V
    S --- V
  end
  L --> C
  P --> C
  GH[GitHub Actions] -->|tag: build, then deploy over SSH| vm
  V -. nightly restic, encrypted .-> B[(B2 or R2)]
  vm -. dead-man pings .-> HC[healthchecks.io]
Loading

Pieces

File Purpose
Dockerfile One image: API, built console, scheduler. Runs as a non-root user.
deploy/compose.yaml Services api, scheduler, caddy, and a restic backup tool.
deploy/Caddyfile HTTPS, security headers, reverse proxy to the API.
deploy/cloud-init.yaml, infra/terraform/hetzner/ Create and set up the server (Docker, firewall, updates, volume, Tailscale).
deploy/scripts/deploy.sh, rollback.sh Deploy with snapshot, backup, migrations, health check and automatic rollback.
deploy/backup/ Nightly backup, monthly restore test, disaster restore.
deploy/monitor/check-host.sh Disk, memory, load and container checks every 5 minutes.
.github/workflows/release.yml, deploy.yml Build and publish the image on a tag, then deploy.

Steps

  1. Create the server with Terraform (terraform apply in infra/terraform/hetzner) or by hand with cloud-init.yaml.
  2. Set secrets in /opt/stonks/deploy/.env on the server (copy deploy/.env.example, chmod 600). Secrets live only there, never in the image or the repo.
  3. Release: bump version in pyproject.toml, then git tag v0.1.0 && git push origin v0.1.0. CI builds the image, makes a GitHub release and deploys.
  4. Open https://stonks.<tailnet>.ts.net and enter STONKS_API_TOKEN in Settings.

Updates and rollback

Every release deploys itself: pull, stop, snapshot, off-site backup, stonks db init, start, health check. If the new version is not healthy within 3 minutes it rolls back on its own.

/opt/stonks/deploy/scripts/rollback.sh               # previous tag, data as is
/opt/stonks/deploy/scripts/rollback.sh --with-data   # also restore the pre-deploy snapshot

Backups and monitoring

  • Nightly encrypted restic backup to Backblaze B2 or Cloudflare R2 (7 daily, 4 weekly, 12 monthly), a restore test on the 1st of each month.
  • healthchecks.io pings for the host check, backup and restore test (HC_PING_* in .env).
  • Logs: docker compose logs -f api scheduler.

Cost

About 6 to 10 EUR a month for a 2 vCPU, 4 GB VM, a 20 GB volume and object storage, plus Tailscale seats.

Full guide, including public HTTPS mode and Windows without Docker: docs/deploy.md in the repo. Runbook: docs/runbooks/deploy-failed.md.

Clone this wiki locally