Skip to content

Server setup guide

This page is a short index for edge-node setup. The automated provisioner (provisioner/) handles all of this non-interactively over SSH. These docs are for operators who need to understand what the automation does, debug a failed provision, or set up a node by hand.

Prerequisites

An edge node must be a fresh Debian 12 or Ubuntu 22.04+ host with:

  • Root SSH access (key auth) from your operator workstation.
  • Outbound internet access to apt.debian.org / get.docker.com / dl.cloudsmith.io.
  • Inbound: port 22 (initial SSH), 80/tcp, 443/tcp, 51820/udp (for all-in-one / edge roles). The hardening phase locks down everything else with UFW.
  • At least 2 GB RAM and 20 GB disk (Standard 4 GB on Linode is the reference plan used by scripts/stage_deploy_linode.py).
  • A DNS A record pointing {slug}.{base_domain} (and registry.{slug}.{base_domain}) at the server IP before the TLS step runs, since Caddy needs to resolve the names for HTTP-01. The wildcard *.{slug}.{base_domain} needs DNS-01 and a CF_API_TOKEN environment variable for the Cloudflare plugin.

Detailed setup notes

The two files below document the full manual procedure and the three-server staging validation runbook. They live alongside this guide in docs/operations/.

Server setup notes

Maps every automated provisioning phase to its manual equivalent shell commands. Read this when:

  • You need to understand exactly what the automation does.
  • A provision run failed mid-phase and you are doing manual remediation.
  • You are setting up a self-hosted node without the SaaS control plane.

Phases covered:

Phase What it does
Phase 1 — system apt-get dist-upgrade
Phase 2 — packages Docker, Caddy, WireGuard (role-scoped)
Phase 3 — hardening SSH drop-in, UFW, kernel sysctls
Phase 4 — services WireGuard gateway, private registry, app compose up
Phase 5 — healthchecks docker / app HTTPS / TLS cert / registry v2 / wg0

Three-server validation runbook

Step-by-step preflight, functional staging, load/soak tests, and failure drills for a three-role deployment (Server A: registry, Server B: control-plane app, Server C: VPN). Read this when:

  • You are validating a new deployment before opening an event.
  • You are doing capacity planning or load testing.
  • You want acceptance criteria to gate a go/no-go decision.

Automated provisioning

If you are running the SaaS control plane and want to provision a new tenant automatically, see Provisioning tenants. That page covers TenantSpec, the phase pipeline, the audit chain, and the scripts/stage_deploy_linode.py end-to-end runner.

For the Docker Compose deployment used on each provisioned node, see Deploy with Docker Compose.