Skip to content

Docker Deployments

Docker gives you two comfortable shapes: a single container when one instance is enough, and a compose stack with tango when the server has real users. Kubernetes is not required: tango drives role changes through the Docker Engine API.

Terminal window
vski install # pulls vski.sh/x/vski:latest-standalone
vski serve # http://127.0.0.1:3000, data in ~/.vski/data

vski serve runs the container in the foreground (Ctrl-C stops it), generates a persistent JWT_SECRET into ~/.vski/serve.env so tokens survive restarts, and keeps data in ~/.vski/data. Useful flags:

Terminal window
vski serve --detach # run in the background
vski serve 3001 /path/to/data # custom port and data directory
vski serve --env S3_BUCKET=... # any env the server reads
vski doctor # server, auth, docker and image checklist

The CLI page covers the full lifecycle (setup, apply, login…). For backups on this shape, Backup has the stop-snapshot-start cron script.

Production on one host: compose with tango

Section titled “Production on one host: compose with tango”

A production stack on a single docker host is three vski nodes (one master, two replicas; the last one doubles as the backup node), Redis for the write journal, and tango as the front door. The canonical, tested version of this compose lives in the tango repository (bench/docker-compose.yml): pick your setup from there; below is the same pattern with a dedicated backup replica.

docker-compose.yml
name: vski
x-vski: &vski
image: vski.sh/x/vski:latest-standalone
restart: unless-stopped
networks: [vski]
# Docker role protocol: tango keeps /etc/vski-roles/<node>; once a node's
# file exists it wins over the REPLICA_MODE it was created with, so
# promotions survive restarts with no reconfiguration.
command:
- sh
- -c
- 'ROLE=$$(cat "/etc/vski-roles/$$VSKI_NODE" 2>/dev/null); export REPLICA_MODE="$${ROLE:-$$REPLICA_MODE}"; exec /app/vski'
x-vski-env: &vski-env
DATA_DIR: /data
JWT_SECRET: ${JWT_SECRET} # openssl rand -hex 24; same everywhere
# replicas sync through tango's management port, which forwards to
# whichever node is master, so they follow every promotion
MASTER_URL: http://tango:8001
SYNC_INTERVAL: "5"
# S3 file storage (recommended): every node reads the same bucket
# S3_ENDPOINT: minio:9000
# S3_BUCKET: vski-files
# S3_ACCESS_KEY: ...
# S3_SECRET_KEY: ...
# S3_FORCE_PATH_STYLE: "true"
services:
redis:
image: redis:8-alpine
restart: unless-stopped
networks: [vski]
vski-0:
<<: *vski
environment: { <<: *vski-env, VSKI_NODE: vski-0, REPLICA_ID: vski-0, REPLICA_MODE: master }
volumes: [ vski-0:/data, roles:/etc/vski-roles:ro ]
vski-1:
<<: *vski
environment: { <<: *vski-env, VSKI_NODE: vski-1, REPLICA_ID: vski-1, REPLICA_MODE: replica }
volumes: [ vski-1:/data, roles:/etc/vski-roles:ro ]
# the backup node: no client traffic, snapshotted stopped every night
vski-backup:
<<: *vski
environment: { <<: *vski-env, VSKI_NODE: vski-backup, REPLICA_ID: vski-backup, REPLICA_MODE: replica }
volumes: [ vski-backup:/data, roles:/etc/vski-roles:ro ]
tango:
image: vski.sh/x/tango:v1.0.2
restart: unless-stopped
networks: [vski]
ports:
- "8000:8000" # clients go here
- "127.0.0.1:8001:8001" # management: promotion + replica sync, host-only
environment:
TANGO_JWT_SECRET: ${JWT_SECRET}
TANGO_NODES: http://vski-0:3000,http://vski-1:3000,http://vski-backup:3000
TANGO_REDIS_ADDR: redis:6379
TANGO_ACTUATOR: docker
TANGO_DOCKER_ROLES_DIR: /roles
TANGO_READ_YOUR_WRITES: 5s
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- roles:/roles
depends_on: [redis]
networks:
vski:
volumes:
vski-0:
vski-1:
vski-backup:
roles:

Bring the stack up (the images are published for amd64 and arm64):

Terminal window
echo "JWT_SECRET=$(openssl rand -hex 24)" > .env
docker compose up -d

Point everything (SDKs, the web UI, workers) at http://<host>:8000. Writes are journaled and hit the master; reads spread over the nodes; if the master container dies, tango hot-promotes the most-current replica and the stack keeps serving. Realtime and workflows work through tango like on a single node.

Notes on the pieces:

  • /var/run/docker.sock is how tango actuates: fencing the dead master, rewriting role files on promotion. The roles volume is the source of truth nodes read at start; that’s why every vski container mounts it read-only.
  • Port 8001 stays host-only. It carries the promotion controls and the replica sync traffic; the only reason it is published at all is your operator shell (curl localhost:8001/tango/status).
  • Files: with the S3_* variables commented out, replicas sync file payloads from the master over HTTP, which is fine to start. Uncomment them (MinIO on the same host works well) and files live in the bucket instead; see File Sync.

The backup node exists to be stopped: a nightly job pauses it, snapshots its volume while nothing can touch the WAL, and starts it again; it resyncs from the changeset log, and production never pauses. This is the procedure from Backup applied to this compose file:

#!/bin/bash
# /usr/local/bin/vski-backup.sh - nightly: 0 3 * * *
set -euo pipefail
cd /srv/vski # where docker-compose.yml lives
BACKUP_DIR=/var/lib/vski/backups
DATE=$(date +%F_%H%M%S)
docker compose stop vski-backup # clean stop checkpoints the WAL
tar -C "$(docker volume inspect vski_vski-backup --format '{{ .Mountpoint }}')" \
-czf "$BACKUP_DIR/$DATE.tar.gz" .
docker compose start vski-backup # resyncs from the changeset log
find "$BACKUP_DIR" -name "*.tar.gz" -mtime +30 -delete

Keep the stop short compared to REPLICATION_LOG_RETENTION_HOURS (default 24) and the wake-up is an incremental sync; restore is DATA_DIR pointed at the unpacked snapshot: a complete standalone server.

Terminal window
curl -s localhost:8001/tango/status | jq # roles, health, lag, journal, leader
# manual failover (tango also does this automatically)
curl -X POST localhost:8001/tango/promote \
-H 'Content-Type: application/json' -d '{"target": "http://vski-1:3000"}'

Upgrades: replicas first, master last: a replica running an older version than the master stays readable but stale (tango drops it from the read pool) until upgraded.

Terminal window
docker compose pull
docker compose up -d vski-backup vski-1 # replicas first
docker compose up -d vski-0 # then the master
docker compose up -d # tango, redis

Moving beyond one host: compose gives you process failure handling, not host failure handling. When that starts to matter, the same topology is one helm install away; Tango covers the chart, storage and scaling.