Skip to content

Home Servers

A home server rarely needs a cluster, but it does need its data to survive disk failures, power cuts and upgrades. Pick the shape by what you expect from the box:

You haveRun
One instance, light load, files on one diskdocker compose, one container
Backups without pauses, some load, failoverDocker Desktop / Rancher Kubernetes + the Helm chart

One VSKI server already covers a family or hobby deployment: collections, graphs, realtime, workflows and the web UI in a single container.

docker-compose.yml
services:
vski:
image: vski.sh/x/vski:latest-standalone
restart: unless-stopped
ports:
- "3000:3000"
environment:
JWT_SECRET: "${JWT_SECRET}" # openssl rand -hex 24, kept in .env
DATA_DIR: /data
volumes:
- vski-data:/data
volumes:
vski-data:

docker compose up -d and the server is on http://<host>:3000; the installer page at / creates the first admin. If you prefer not to write a compose file at all, vski serve wraps the same thing in one command (see Docker deployments and the CLI).

Backups: a cron job that stops the container, snapshots the volume and starts it again; the full script is in Backup. Restoring is copying the snapshot back.

When the deployment starts to matter (backups that never pause the server, read scaling, a master failure handled in milliseconds), the answer is not more docker plumbing but the cluster chart. The easiest way to run it at home is the Kubernetes that ships with your docker tools:

  • Docker Desktop: Settings → Kubernetes → Enable. Nothing to configure; kubectl is included.
  • Rancher Desktop: pick the embedded Kubernetes in the preferences.

Both give you a single-node cluster. The images are pulled from vski.sh/x and built for amd64 and arm64, so Apple silicon Macs and arm64 boxes work as is: no registry to set up, nothing to build.

Terminal window
git clone https://vski.sh/x/k8s.git
helm upgrade --install vski ./k8s/vski-cluster \
--set image.tag=v0.17.7-standalone # server + web UI

That installs the whole stack (master, two replicas, tango with automated failover, the write journal in Redis) on your box, with a JWT secret generated once and kept across upgrades. Tango explains what each piece does and how to scale it later.

The cluster publishes one client Service, vski-vski on port 3000: that is tango, the only address anything should ever talk to. Expose it however your network is shaped:

Terminal window
# quick access from your desktop
kubectl port-forward svc/vski-vski 3000:3000
# or a stable port on the host itself
helm upgrade vski ./k8s/vski-cluster --reuse-values --set service.type=NodePort
kubectl get svc vski-vski # the NodePort column is your port

Point your SDKs, the dashboard bookmark and your reverse proxy at that port.

The highest-ordinal replica doubles as the backup node: a nightly job scales the StatefulSet down by one (stopping that pod), snapshots its PVC, scales back up, and the pod resyncs from the changeset log on wake. Check first that it is still a replica: after a promotion it can be the master. Production traffic never notices; the procedure and the restore path are in Backup.

Single-host Kubernetes protects against process failures, not host failures. The day the deployment becomes something you’d be sad to lose with the machine, move the same chart to a real cluster (two nodes and a NAS-backed StorageClass already change the story); nothing else about the deployment changes. See Tango for storage, scaling and upgrade procedures.