Why this setup
- Only your devices can reach it. Nothing listens on the public internet, so strangers have no login page to try.
- A real certificate. Caddy gets a Let’s Encrypt certificate for the server’s
*.ts.netname, so phones, browsers and MCP clients trust it without extra steps. - The same everywhere. It works on any VPS provider or on a box at home behind any router, with no port forwarding.
The trade-off: each phone and computer needs Tailscale installed and connected to reach the server.
Pick a machine
- A VPS from any provider: one or two vCPUs, 1–2 GB of RAM and a recent Ubuntu LTS or Debian. That’s plenty for one household.
- A home server: a mini PC or other always-on Linux box, x86-64 or 64-bit ARM.
Building the server with Gradle on a 1 GB machine can be slow. Use the release zip instead.
Prepare the server
Do this before anything else runs on the box. The commands are for Ubuntu and Debian.
- Update everything and turn on automatic security updates.
sudo apt update && sudo apt full-upgrade -y sudo apt install -y unattended-upgrades sudo dpkg-reconfigure -plow unattended-upgrades - Use SSH keys only. Work as a normal user with sudo, not root. Copy your key with
ssh-copy-idand check you can log in with it. Then set these in/etc/ssh/sshd_configand reload withsudo systemctl reload ssh:PasswordAuthentication no PermitRootLogin no - Turn on the firewall, denying everything incoming by default.
If your provider has its own firewall (often called a security group), allow only SSH there too.sudo ufw default deny incoming sudo ufw default allow outgoing sudo ufw allow OpenSSH sudo ufw enable - Install Docker Engine from Docker’s official packages, running as root (not rootless). Check that
docker compose versionsays 2.24.4 or newer.
Tailscale on the server
- Install Tailscale and sign in.
curl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up - Turn on MagicDNS and HTTPS Certificates in the Tailscale admin console. Consider turning off key expiry for this machine, so it doesn’t drop off your tailnet.
- Note its address and name.
tailscale ip -4 # 100.x.y.z tailscale status --json | jq -r .Self.DNSName # your-server.your-tailnet.ts.net. (drop the final dot)
Certificates are public records: your machine name and tailnet name appear in public certificate-transparency logs. Choose names that say nothing about you.
Once Tailscale works, you can limit SSH to the tailnet too: run sudo ufw allow in on tailscale0, check that you can SSH over the tailnet, then run sudo ufw delete allow OpenSSH.
Tailscale on your phones and computers
- Install Tailscale from Google Play on every phone that runs Orbit Health or OrbitWalker, and sign in to the same tailnet. It runs as a VPN, so keep it connected. Android’s Always-on VPN setting helps.
- Install it on the computer you’ll use for the dashboard and for MCP tools.
Start Orbit Server on the tailnet
- Get the code and the server build, as in Install, steps 1 and 2.
- Write
deploy/.envwith exactly these four lines, then runchmod 600 .env:COMPOSE_FILE=docker-compose.yml:docker-compose.tailscale.yml ORBIT_DOMAIN=your-server.your-tailnet.ts.net ACME_EMAIL=you@example.com # required by the Caddyfile, unused for ts.net certificates TAILSCALE_IP=100.x.y.z - Check, then start.
cd deploy docker compose config | grep -A3 published # every published port: host_ip 100.x.y.z docker compose up -d --build docker compose ps # PORTS: 100.x.y.z:443->443 only docker compose logs --tail 30 orbit # the one-time setup code - Finish setup from a device on your tailnet at
https://your-server.your-tailnet.ts.net/. See First run.
Why the override matters
Docker writes its own firewall rules for published ports, and they take effect before ufw’s. A port Docker publishes on every address is reachable from the internet even when ufw says deny. So docker-compose.tailscale.yml doesn’t rely on the firewall. It replaces the public 80 and 443 with 443 on the Tailscale address only, so the public interface has nothing listening in the first place. Port 80 isn’t needed, because the certificate comes from Tailscale with no public challenge.
The COMPOSE_FILE line makes every plain docker compose command in deploy/ use the override, including up, logs, the backup and the update. Without it, up publishes 80 and 443 on every address. Never remove it, and never publish port 8080.
How the certificate works
The override mounts the host’s tailscaled socket into Caddy. For a *.ts.net name, Caddy asks Tailscale for a real Let’s Encrypt certificate through it, and renews it by itself.
That socket gives Caddy, which runs as root in its container, admin control of Tailscale on the host. The :ro flag doesn’t limit that. If you’d rather not grant it, use certificate files from tailscale cert instead. The README has the steps, and you’ll need to renew within 90 days.
After a reboot
Docker can only publish on 100.x.y.z once Tailscale has that address. If Docker starts first, Caddy fails with “cannot assign requested address”. Fix the order once with a systemd drop-in:
sudo systemctl edit docker.service
# add:
[Unit]
Wants=tailscaled.service
After=tailscaled.service
On a slow network the address can still arrive late. The README describes a second option.
Check nothing is public
docker compose psshows100.x.y.z:443and nothing else.sudo ss -tlnpshows no listener on0.0.0.0:80,:443or:8080.- From a device on your tailnet,
https://your-server.your-tailnet.ts.net/healthanswers with"ok":true. - Turn Tailscale off on your phone and try again: the server should be unreachable.
Keep it healthy
- Leave unattended upgrades on, and reboot when the system asks for it, for example after kernel updates.
- Keep the firewall denying incoming connections by default, and SSH on keys only.
- Keep
deploy/.envat mode 600 and out of any repository. - Don’t run unrelated public services on the same machine.
- Glance at the dashboard’s Devices and Access log now and then. Revoke anything you don’t recognise.
Backups
Back up the whole data volume. It holds your health data, conversations, the master key that decrypts your provider keys, and the certificate and pairings your phones rely on. Run this in deploy/:
docker compose stop orbit
(umask 077 && docker run --rm -v orbit_orbit-data:/data:ro eclipse-temurin:17-jre \
tar -czf - -C /data . > ~/orbit-server-backup-$(date +%F).tgz)
docker compose start orbit
- Keep backups private. Anyone with the archive has your data and can decrypt your provider keys. Encrypt it before it leaves the server (for example
gpg -c), and store it somewhere only you can reach. Copying it over your tailnet withscpworks well. - Keep more than one. Keep a few dated copies, and try a restore once (see Restore) so you know it works.
Updating safely
- Back up, as above.
- Pull and build:
git pull, then./gradlew :server:installDistor unpack the new release zip. - Restart:
cd deploy && docker compose up -d --build - Check:
docker compose psstill shows only100.x.y.z:443, andhttps://your-server.your-tailnet.ts.net/healthanswers"ok":true.
If something is wrong, check out the previous release tag, rebuild and restore your backup.
Public domain instead
You can also run Orbit Server on the open internet with your own domain. That’s the base docker-compose.yml, without the Tailscale override. Caddy publishes 80 and 443 and gets a Let’s Encrypt certificate for your domain.
- Create an A record only, with no AAAA record. The bundled network is IPv4-only, and IPv6 clients would share one rate limit.
- In
.env, setORBIT_DOMAIN=orbit.example.comandACME_EMAIL, and leave out the Tailscale lines. - In your provider’s firewall, allow 80/tcp, 443/tcp, 443/udp and SSH. Docker-published ports bypass ufw, so the provider’s firewall is the one that counts. Never open 8080.
You gain
- Phones reach the server from anywhere, without Tailscale
- One less service to run on each device
You give up
- The login page, pairing and APIs face the whole internet. The password, rate limits and CSRF checks protect them, but scanners will find them.
- Keeping it patched matters more
- Your domain is public