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.
One instance: vski serve
Section titled “One instance: vski serve”vski install # pulls vski.sh/x/vski:latest-standalonevski serve # http://127.0.0.1:3000, data in ~/.vski/datavski 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:
vski serve --detach # run in the backgroundvski serve 3001 /path/to/data # custom port and data directoryvski serve --env S3_BUCKET=... # any env the server readsvski doctor # server, auth, docker and image checklistThe 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.
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):
echo "JWT_SECRET=$(openssl rand -hex 24)" > .envdocker compose up -dPoint 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.sockis 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 job
Section titled “The backup job”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 livesBACKUP_DIR=/var/lib/vski/backupsDATE=$(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 -deleteKeep 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.
Operating the stack
Section titled “Operating the stack”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.
docker compose pulldocker compose up -d vski-backup vski-1 # replicas firstdocker compose up -d vski-0 # then the masterdocker compose up -d # tango, redisMoving 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.