Skip to content
Beta

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.

ProviderButtonWhat it creates
AWSLaunch Stack in AWSA 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 AzureDeploy to AzureA 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 CloudOpen in Cloud ShellCloud Shell with the Terraform kit open: run terraform init && terraform apply. A Shielded VM with no firewall rule.
Oracle CloudDeploy to Oracle CloudA 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.

PlatformHow
Dockerdocker 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.
RenderDeploy to Render: a background worker with a 20 GB disk at /data (a paid plan). The worker's Logs show the link.
Fly.iofly 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.
RailwayNew 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:

WayBest forDownload
One paste (cloud-init)Any provider's console: DigitalOcean, Hetzner, Akamai, Vultr, AWS, Google Cloud, Azure…cloud-init.yaml
One commandA Linux machine you already haveinstall-server.sh
Terraform on AWSEC2, as codespandock-terraform-aws.zip
Terraform on Google CloudCompute Engine, as codespandock-terraform-gcp.zip
AnsibleFleets of hosts you managespandock-ansible.zip

The kits are also on GitHub, under the Apache 2.0 license: SpanDock/spandock-deploy.

Every way installs the same thing:

  • a spandock service 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.
ProviderA good start (2 vCPU, 4 GB)ARM option
AWSt3.mediumt4g.medium
Google Cloude2-mediumt2a-standard-1 or larger
AzureB2sB2pls v2
DigitalOceanBasic 2 vCPU / 4 GB—
HetznerCPX21CAX11
Vultr, Akamai2 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:

ProviderWhere to paste
DigitalOceanCreate Droplet → Advanced options → Add initialization scripts
HetznerAdd server → Cloud config
Akamai (Linode)Create Linode → Add User Data
VultrDeploy → Additional features → Cloud-Init User-Data
AWS EC2Launch instance → Advanced details → User data
Google CloudCreate instance → Advanced → Management → Metadata: key user-data, the file as value
AzureCreate 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 at https://<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 with AmbientCapabilities=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=443 in /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_service works too: from version 0.20, SpanDock keeps that permission across updates when it can, and otherwise shows the sudo setcap … command to run under Settings → Updates. A unit you write yourself should also set KillMode=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:

WhereHow
Over SSHjournalctl -u spandock -f
AWSEC2 → the instance → Actions → Monitor and troubleshoot → Get system log, or the Terraform activation command
Google CloudThe instance → Serial port 1 (console), or the Terraform activation command
AzureThe VM → Help → Boot diagnostics → Serial log
OthersThe 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.

  1. On the hub, open Settings → Scaling → Add server and copy the join code. It works once, for 30 minutes.
  2. 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=….

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

WhatWhere
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
Logsjournalctl -u spandock
The sidekicksystemctl status spandock-sidekick, journalctl -u spandock-sidekick
Healthcurl 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.

Cookie categories

Details: Cookie Policy.