Deploy a server in the cloud
Run your SpanDock Server on a cloud VM, so it's always on for the whole team. Clients reach it over the encrypted tunnel, so no inbound port and no public address are needed: the VM only connects out.
One click
Each button opens the provider's own console with SpanDock's template filled in: check the size and the region, create, then activate the server. Nothing reaches the machine from outside; it only connects out.
| Provider | Button | What it creates |
|---|---|---|
| AWS | Launch Stack in AWS | A CloudFormation stack: an EC2 instance (t3.medium; arm64 with t4g) with Ubuntu 24.04, an encrypted gp3 disk, IMDSv2 and a security group with no inbound rule, in the default VPC. Template: spandock-aws.yaml. |
| Microsoft Azure | Deploy to Azure | A VM (Standard_B2s) with Ubuntu 24.04, Trusted Launch, boot diagnostics, a network security group with no inbound rule, and its own network. Azure asks for an SSH public key; SSH stays closed. Template: azuredeploy.json. |
| Google Cloud | Open in Cloud Shell | Cloud Shell with the Terraform kit open: run terraform init && terraform apply. A Shielded VM with no firewall rule. |
| Oracle Cloud | Deploy to Oracle Cloud | A Resource Manager stack: an instance on the Always Free Ampere shape (2 OCPUs and 12 GB by default, up to 4 and 24 free) with Ubuntu 24.04, in its own network with no inbound rule. Stack: spandock-oracle-stack.zip. |
For a satellite, paste the hub's join code (Settings → Scaling → Add server) into the form's join code field.
Containers
Every release is also a container image for servers, ghcr.io/spandock/spandock (amd64 and arm64). Run it with a persistent volume at /data and no public port: clients reach it over its encrypted tunnel, which only connects out. Its log shows the activation link. A new image is the update.
| Platform | How |
|---|---|
| Docker | docker run -d --name spandock --restart unless-stopped -v spandock-data:/data -e SPANDOCK_ACCEPT_EULA=1 ghcr.io/spandock/spandock, then docker logs spandock. Or docker-compose.yml. |
| Render | Deploy to Render: a background worker with a 20 GB disk at /data (a paid plan). The worker's Logs show the link. |
| Fly.io | fly launch --from https://github.com/spandock/spandock-deploy --copy-config --no-deploy, then fly deploy and fly logs: a Machine (2 shared CPUs, 4 GB) with a 20 GB volume and no public service. |
| Railway | New project → Deploy a Docker image → ghcr.io/spandock/spandock; add a volume at /data and the variable SPANDOCK_ACCEPT_EULA=1; don't generate a domain. The deployment's logs show the link. |
SPANDOCK_ACCEPT_EULA=1 accepts the EULA; for a satellite, set SPANDOCK_JOIN_CODE on its first start. Manage the server from a paired client (Open server dashboard), or with docker exec spandock spandock admin … (on Fly.io, fly ssh console; on Render and Railway, the service's shell).
One command: Hetzner and DigitalOcean
They have no deploy button, so it's one command with their own CLI (or the cloud-init paste in their console).
Hetzner Cloud (hcloud, CPX21 in Falkenstein; CAX11 for ARM):
curl -fsSL https://spandock.com/deploy/cloud-init.yaml -o spandock-cloud-init.yaml
hcloud server create --name spandock --type cpx21 --image ubuntu-24.04 --location fsn1 --user-data-from-file spandock-cloud-init.yaml
DigitalOcean (doctl, 2 vCPU and 4 GB in Frankfurt):
curl -fsSL https://spandock.com/deploy/cloud-init.yaml -o spandock-cloud-init.yaml
doctl compute droplet create spandock --size s-2vcpu-4gb --image ubuntu-24-04-x64 --region fra1 --user-data-file spandock-cloud-init.yaml --wait
Then activate the server: hcloud server request-console spandock or the Droplet's Recovery Console shows the link, as does journalctl -u spandock over SSH.
Kubernetes
From version 0.63, every release has a Helm chart:
helm install spandock oci://ghcr.io/spandock/charts/spandock \
--namespace spandock --create-namespace --set eula.accept=true
kubectl logs -n spandock statefulset/spandock | grep -i activat
kubectl port-forward -n spandock statefulset/spandock 8787 # then http://127.0.0.1:8787
The chart runs one server, as a StatefulSet with a volume, non-root and read-only. A satellite is the same chart with joinCodeSecret, and the public endpoint is publicEndpoint.enabled=true. Air-gapped installs pass the offline license through licenseSecret.
Other ways
Pick one way:
| Way | Best for | Download |
|---|---|---|
| One paste (cloud-init) | Any provider's console: DigitalOcean, Hetzner, Akamai, Vultr, AWS, Google Cloud, Azure… | cloud-init.yaml |
| One command | A Linux machine you already have | install-server.sh |
| Terraform on AWS | EC2, as code | spandock-terraform-aws.zip |
| Terraform on Google Cloud | Compute Engine, as code | spandock-terraform-gcp.zip |
| Ansible | Fleets of hosts you manage | spandock-ansible.zip |
The kits are also on GitHub, under the Apache 2.0 license: SpanDock/spandock-deploy.
Every way installs the same thing:
- a
spandockservice account; - the release, checked against its published checksums;
- a systemd service that restarts on failure.
The server keeps itself up to date when Install updates automatically is on in its settings.
What to choose
- System: Ubuntu 24.04 or later, or Debian 13. SpanDock needs glibc 2.38 or later. x86-64 or ARM64.
- Size: 2 vCPU, 4 GB of memory and 30 GB of disk suit up to about 50 developers. For a larger team or longer history, use the hardware calculator.
- Network: outbound HTTPS. Nothing has to reach the machine; open SSH only if you want it.
| Provider | A good start (2 vCPU, 4 GB) | ARM option |
|---|---|---|
| AWS | t3.medium | t4g.medium |
| Google Cloud | e2-medium | t2a-standard-1 or larger |
| Azure | B2s | B2pls v2 |
| DigitalOcean | Basic 2 vCPU / 4 GB | — |
| Hetzner | CPX21 | CAX11 |
| Vultr, Akamai | 2 vCPU / 4 GB shared CPU | — |
One paste: cloud-init
Create a VM with Ubuntu 24.04 and paste cloud-init.yaml into the user data field:
| Provider | Where to paste |
|---|---|
| DigitalOcean | Create Droplet → Advanced options → Add initialization scripts |
| Hetzner | Add server → Cloud config |
| Akamai (Linode) | Create Linode → Add User Data |
| Vultr | Deploy → Additional features → Cloud-Init User-Data |
| AWS EC2 | Launch instance → Advanced details → User data |
| Google Cloud | Create instance → Advanced → Management → Metadata: key user-data, the file as value |
| Azure | Create a virtual machine → Advanced → Custom data |
Then activate the server.
One command
On a Linux machine you already have:
curl -fsSL https://spandock.com/deploy/install-server.sh | sudo bash
It prints the activation link when it's done. Run it again at any time to repair or upgrade the install; your data and settings stay.
Options, as environment variables after sudo:
SPANDOCK_VERSION=v0.14.0: pin a release.SPANDOCK_JOIN_CODE=…: join a hub as a satellite.SPANDOCK_PUBLIC_LISTEN=0.0.0.0:443,SPANDOCK_PUBLIC_NAME=…,SPANDOCK_PUBLIC_DOMAIN=…,SPANDOCK_ACME_EMAIL=…: turn on the public endpoint with automatic HTTPS athttps://<name>.<domain>(version 0.18 or later). Open inbound TCP 443 and create the DNS record pointing at the machine first. The kit's service may listen on 443 without running as root (a systemd unit withAmbientCapabilities=CAP_NET_BIND_SERVICE). Installed another way? In order of preference: a systemd system unit with that line, running as a dedicated user;net.ipv4.ip_unprivileged_port_start=443in/etc/sysctl.d/50-spandock.conf(fine on a machine used only for SpanDock); or a container that maps 443 to an unprivileged port.setcap cap_net_bind_serviceworks too: from version 0.20, SpanDock keeps that permission across updates when it can, and otherwise shows thesudo setcap …command to run under Settings → Updates. A unit you write yourself should also setKillMode=process, so stopping the old process doesn't stop the update's rollback check.
For example: curl -fsSL … | sudo SPANDOCK_VERSION=v0.14.0 bash.
Terraform on AWS
Download spandock-terraform-aws.zip. It creates one EC2 instance with:
- Ubuntu 24.04;
- an encrypted gp3 disk;
- IMDSv2 required;
- a security group with no inbound rule.
cp terraform.tfvars.example terraform.tfvars # region, instance type, disk
terraform init && terraform apply
The activation output is a command that reads the instance's console and prints the activation link. Settings in variables.tf:
- your own subnet;
- an SSH key and an allowed address;
- Graviton (
architecture = "arm64"); - a pinned version;
- a satellite join code.
Terraform on Google Cloud
Download spandock-terraform-gcp.zip, or open it in Cloud Shell to run it from your browser, already signed in to your project. It creates one Compute Engine VM with Ubuntu 24.04, as a Shielded VM, and no firewall rule.
cp terraform.tfvars.example terraform.tfvars # project, region, machine type, disk
gcloud auth application-default login
terraform init && terraform apply
The activation output reads the serial port and prints the activation link. On a network with Cloud NAT, set external_ip = false.
Ansible
Download spandock-ansible.zip for machines you already manage:
cp inventory.example.ini inventory.ini # your hosts
ansible-playbook -i inventory.ini site.yml
The role checks the platform, installs the release, and installs and starts the service. For each new hub it prints the activation link. Running it again upgrades to spandock_version and keeps all data.
Activate the server
A new SpanDock Server is approved once, by you, on spandock.com. A few minutes after boot it prints a link. Open it on any device, sign in, check the code matches what the server shows, and approve. The license is then stored on the server, and restarts don't ask again.
Where to read the link:
| Where | How |
|---|---|
| Over SSH | journalctl -u spandock -f |
| AWS | EC2 → the instance → Actions → Monitor and troubleshoot → Get system log, or the Terraform activation command |
| Google Cloud | The instance → Serial port 1 (console), or the Terraform activation command |
| Azure | The VM → Help → Boot diagnostics → Serial log |
| Others | The provider's web or recovery console |
The code expires after a few minutes; the server then prints a new one by itself.
After installing
The kit adds a spandock command to the machine. It runs SpanDock commands as the service account with the service's settings, so use it instead of the binary itself:
sudo spandock onboard # set it up by answering questions: hub or satellite, public endpoint
spandock license status # the server's license
spandock admin pair # add a client (prints a pairing code)
spandock service create … # a service key for a cloud tool
journalctl -u spandock -f # follow the server's log
spandock onboard asks whether this is a new hub or a satellite (and for the join code, hidden as you type), and whether to turn on the public endpoint. It saves the answers in /etc/spandock/server.env, which only root and the service can read, and restarts the service. Use it on a new server, before it's activated or joined.
Running 0.21.1 or older? Servers installed with the kit before 0.21.2 can't update themselves. Run the install command above once to move to the latest version; after that they update themselves again.
The server itself runs as the spandock systemd service (systemctl status spandock); spandock on its own doesn't start a second one. The dashboard listens only on the machine itself. To open it, tunnel it over SSH and browse to http://127.0.0.1:8787:
ssh -L 8787:127.0.0.1:8787 <your server>
The sidekick
From version 0.22, a small helper called the sidekick watches the server. If SpanDock hangs or crashes, the sidekick restarts it. If a critical update is out and SpanDock's own updater can't install it, the sidekick installs it. The kit runs it as a second service, spandock-sidekick. SpanDock puts the sidekick's program in place about 20 seconds after its first start, and the service starts by itself once it's there. spandock sidekick -once runs a single check and prints what it found, which helps when troubleshooting. The sidekick uses any proxy or certificate settings in /etc/spandock/server.env for its downloads.
Add satellites
Satellites share the load and let clients fail over. They need Premium or Enterprise.
- On the hub, open Settings → Scaling → Add server and copy the join code. It works once, for 30 minutes.
- Create the new VM with the code:
- cloud-init: put it in the
SPANDOCK_JOIN_CODE=''part of the file; - one command:
curl … | sudo SPANDOCK_JOIN_CODE='…' bash; - Terraform:
join_code = "…"; - Ansible:
-e spandock_join_code=….
- cloud-init: put it in the
A satellite follows the hub's license, so it doesn't need its own activation. The join code is used once, on the first start. After that the satellite's settings and cluster credentials stay on the machine, and the service brings it back after every restart. Don't start a satellite by hand in a terminal: it stops when you log out and comes back unjoined (see Satellites and failover).
Where things live
| What | Where |
|---|---|
| The program | /var/lib/spandock/bin/spandock (owned by the service, so it can update itself) |
| Data and settings | /var/lib/spandock/.config/ |
| Service settings | /etc/spandock/server.env |
| Logs | journalctl -u spandock |
| The sidekick | systemctl status spandock-sidekick, journalctl -u spandock-sidekick |
| Health | curl http://127.0.0.1:4318/healthz on the machine |
Back up /var/lib/spandock (or snapshot the disk) to keep the history and settings.
Uninstall
To remove SpanDock and everything the kit installed:
sudo systemctl disable --now spandock-sidekick.path spandock-sidekick spandock
sudo rm -f /etc/systemd/system/spandock.service /etc/systemd/system/spandock-sidekick.service /etc/systemd/system/spandock-sidekick.path
sudo systemctl daemon-reload
sudo rm -f /usr/local/bin/spandock
sudo rm -rf /etc/spandock
sudo userdel -r spandock # also deletes /var/lib/spandock: the history, settings and license
Back up /var/lib/spandock first if you might want the data again. To use the license on another server, release this one first: Settings → License → Deactivate in the app, or the Licenses page of your dashboard.