furtka-gateway/README.md

furtka-gateway

WireGuard (wg-easy) + Traefik reverse-proxy that lets a Furtka box — typically sitting behind NAT/CGNAT with no public IP — expose individual apps to the internet under a real domain with automatic TLS.

A Furtka box becomes a WireGuard peer of this gateway. The gateway's Traefik reverse-proxies public HTTPS traffic over that tunnel to whichever apps the box owner has explicitly published. Only apps whose Furtka manifest.json declares internet.viable: true can be published at all, and publishing is always an explicit per-app opt-in on the box side — the gateway never exposes anything on its own.

Supports two deployment modes from the same codebase:

• single — the common case: one person/operator runs this on their own VPS with their own domain's A/AAAA records pointed at it, for their own Furtka box(es).
• shared — one larger, multi-tenant instance (operated by the Furtka project) for people who don't want to run their own. Same schema, same code; single is just the one-account case.

Status: Phase 2 — the control plane (accounts/boxes/routes, wg-easy peer provisioning, Traefik dynamic-config generation) is built and tested for single-tenant mode. The Furtka-core side (the box-facing "connect to a gateway" flow and per-app "expose to internet" toggle) is still just a plan, not yet implemented — see the plan doc for the phased delivery.

Deploying on a VPS

1. Get a VPS with a static public IP, point a domain's A/AAAA record at it (e.g. example.com), and open 80/tcp, 443/tcp, 51820/udp in whatever firewall/security group sits in front of it.
2. cp .env.example .env and fill it in — in particular GATEWAY_PUBLIC_HOST (the WireGuard endpoint hostname), a wg-easy admin password (WG_EASY_PASSWORD_HASH + the matching plaintext WG_EASY_ADMIN_PASSWORD), GATEWAY_BOX_TOKEN (openssl rand -hex 32), and GATEWAY_CONTROL_PLANE_HOST (its own A/AAAA record — see step 5). Double every $ in WG_EASY_PASSWORD_HASH as $$ — see that variable's comment in .env.example for why; getting this wrong silently truncates the hash instead of erroring, confirmed by hitting it directly.
3. Run sudo ops/host-sysctls.sh on the VPS before bringing the stack up. wg-easy needs net.ipv4.ip_forward=1 (so the host actually routes between the docker bridge and the WireGuard interface — see the network_mode: host comment on the wg-easy service) and net.ipv4.conf.all.src_valid_mark, and — confirmed by actually trying it, not assumed — Docker's own sysctls: key can't set either one once a service is host-networked; runc refuses to even start the container.
4. Bring the stack up: docker compose up -d (or docker stack deploy under Swarm — see the caveats below, build: doesn't work there yet).
5. Copy traefik/dynamic/control-plane.yml.example to traefik/dynamic/control-plane.yml, substituting your real GATEWAY_CONTROL_PLANE_HOST. Without this, the registration API is only reachable at 127.0.0.1:8090 on the VPS itself — a remote Furtka box has no way to reach it, and the call needs TLS anyway since it carries a WireGuard private key (see that file's comments, and control_plane/wgeasy.py's module docstring, for why).
6. Run sudo ops/firewall.sh on the VPS. wg-easy's admin API is no longer kept off the public interface by Docker the way every other service here is (a direct consequence of network_mode: host — see step 3). This script closes that with an iptables rule. Do this before pointing DNS at the box for real — read the script's own caveats first, it hasn't been validated against a real multi-interface VPS yet.
7. curl http://127.0.0.1:8090/healthz from the VPS to confirm the stack is actually up.

Docker Swarm caveats

If deploying via docker stack deploy instead of docker compose up:

• docker-compose.yaml's build: ./control_plane doesn't work under Swarm at all — it only ever schedules pre-built, tagged images. Build and tag the image yourself first (docker build -t furtka-gateway-control-plane:local ./control_plane) and swap build: for image: furtka-gateway-control-plane:local until this is packaged as a versioned image in CI (the planned long-term fix).
• docker stack deploy does not read a .env file next to the compose file the way docker compose up does — set -a; source .env; set +a first, or the ${VAR} substitutions come out empty.
• depends_on is silently ignored by Swarm — harmless here, since control_plane only talks to wg-easy/Traefik lazily on the first real request, not at startup.

Local dev

cp .env.example .env
# GATEWAY_PUBLIC_HOST can be a LAN-reachable IP for a first smoke test.
docker compose up -d
curl http://127.0.0.1:8090/healthz

ops/firewall.sh and the control-plane.yml Traefik route are about reaching this gateway from the real internet — skip both for local dev.