The Orbit Apps

Recommended setup

Orbit Server on a small VPS or a home box, reachable only over your own Tailscale network. No public ports, a real certificate, and a few habits that keep it that way.

TailscaleDocker Compose1–2 GB RAM

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.net name, 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.

  1. 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
  2. Use SSH keys only. Work as a normal user with sudo, not root. Copy your key with ssh-copy-id and check you can log in with it. Then set these in /etc/ssh/sshd_config and reload with sudo systemctl reload ssh:
    PasswordAuthentication no
    PermitRootLogin no
  3. Turn on the firewall, denying everything incoming by default.
    sudo ufw default deny incoming
    sudo ufw default allow outgoing
    sudo ufw allow OpenSSH
    sudo ufw enable
    If your provider has its own firewall (often called a security group), allow only SSH there too.
  4. Install Docker Engine from Docker’s official packages, running as root (not rootless). Check that docker compose version says 2.24.4 or newer.

Tailscale on the server

  1. Install Tailscale and sign in.
    curl -fsSL https://tailscale.com/install.sh | sh
    sudo tailscale up
  2. 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.
  3. 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

  1. Get the code and the server build, as in Install, steps 1 and 2.
  2. Write deploy/.env with exactly these four lines, then run chmod 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
  3. 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
  4. 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 ps shows 100.x.y.z:443 and nothing else.
  • sudo ss -tlnp shows no listener on 0.0.0.0:80, :443 or :8080.
  • From a device on your tailnet, https://your-server.your-tailnet.ts.net/health answers 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/.env at 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 with scp works well.
  • Keep more than one. Keep a few dated copies, and try a restore once (see Restore) so you know it works.

Updating safely

  1. Back up, as above.
  2. Pull and build: git pull, then ./gradlew :server:installDist or unpack the new release zip.
  3. Restart: cd deploy && docker compose up -d --build
  4. Check: docker compose ps still shows only 100.x.y.z:443, and https://your-server.your-tailnet.ts.net/health answers "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, set ORBIT_DOMAIN=orbit.example.com and ACME_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