Skip to content

docs(deploy): run the native systemd unit on port 443 - #433

Merged
vishr merged 3 commits into
mainfrom
docs/native-port-443
Nov 8, 2026
Merged

vishr merged 3 commits into
mainfrom
docs/native-port-443

Conversation

@vishr

@vishr vishr commented Nov 7, 2026 •

Copy link
Copy Markdown
Member

Refs #429. This PR does not close the issue: verifying the unprivileged port-443 run on Linux is still pending and will happen on a Linux test host.

Summary

Docs-only change to the deploy guide (site/src/content/docs/docs/guides/deploy.mdx). A new Listen on port 443 subsection under Run with systemd covers deployments where a TLS-terminating proxy reaches the origin only on 443. For example, Cloudflare's gRPC proxying requires the origin on 443 with TLS and HTTP/2 over ALPN.

The section adds a systemctl edit fanout drop-in that:

  • sets FANOUT_ADDR=:443, which overrides the base unit's loopback address,
  • passes the TLS certificate and key through LoadCredential (%d/...), the same way the guide already handles the auth secret, so the files can stay root-only,
  • grants only CAP_NET_BIND_SERVICE through AmbientCapabilities, with a matching CapabilityBoundingSet and NoNewPrivileges=true. The service still runs as the unprivileged fanout user.

On Cloudflare, it lists the prerequisites: gRPC enabled on the zone (otherwise Cloudflare returns 403), a proxied DNS record, and SSL/TLS mode Full (strict); Cloudflare's minimum is Full. It links Cloudflare's IP ranges for the firewall rule. It also notes that systemd copies credentials and Fanout loads the certificate once at service start, so the service must be restarted after renewal.

It also gives verification commands: systemctl show -p User -p AmbientCapabilities -p CapabilityBoundingSet, ss -ltnp 'sport = :443', /proc/<pid>/status (CapAmb/CapEff should be 0000000000000400, which is CAP_NET_BIND_SERVICE alone), and a curl --resolve readiness check, with --cacert for private or Cloudflare Origin CA certificates. It warns that :443 binds every interface, so the port should be firewalled to the proxy's networks.

No runtime, contract or security behaviour changes.

Verification

  • systemd-analyze verify was not run: the change was prepared on macOS, which has no systemd. The drop-in uses only standard [Service] directives (Environment=, LoadCredential=, AmbientCapabilities=, CapabilityBoundingSet=, NoNewPrivileges=). It was checked by hand against systemd.exec(5) and systemd.unit(5).
  • The acceptance item "running as an unprivileged user on 443 is verified" has not been exercised on a Linux host yet. The guide includes the commands to confirm it, and a reviewer with a Linux host should run them.
  • After the review follow-up commit, just site-build passes again (astro check 0 errors).
  • just site-build: PASS (astro check 0 errors; table, canonical and docs-URL checks pass). just docs-generate-check: PASS.
  • just check (macOS arm64, heavily loaded shared host): every Go and script recipe passed, including script-tests, lint and test, on the second run. The first run's script-tests hit timeouts in the ui-deadcode script tests at ~25–30s per test. ui-test timed out twice on src/dashboards/echarts-brush.test.tsx (5s per-test limit; load average 56–128). The same file passes alone (bun run test -- src/dashboards/echarts-brush.test.tsx: 5/5), and ui-test passed on the same base in another branch's run. This PR changes no code.
  • Pre-push hook on the review follow-up commit: full just check passed (693s).

vishr added 3 commits November 7, 2026 10:59
Some TLS-terminating proxies, such as Cloudflare's gRPC proxying, reach
the origin only on port 443. The deploy guide's unit binds loopback port
7520 as an unprivileged user and gave no way to bind 443 without root.

Document a drop-in that moves FANOUT_ADDR to :443, passes the TLS
certificate and key as systemd credentials, and grants only
CAP_NET_BIND_SERVICE through AmbientCapabilities with a matching
CapabilityBoundingSet and NoNewPrivileges. Include commands to confirm
the process runs as the service user with only that capability.

Closes #429
Review follow-up. Cloudflare's gRPC proxying also needs gRPC enabled on
the zone (otherwise it answers 403), a proxied DNS record and at least
Full encryption; recommend Full (strict) so Cloudflare verifies the
origin certificate. Link Cloudflare's IP ranges for the firewall, note
that credentials are copied and the certificate loaded at service start
so renewal needs a restart, and show --cacert for private or Cloudflare
Origin CA certificates in the readiness check.

Refs #429
@vishr
vishr merged commit ab67628 into main Nov 8, 2026
19 checks passed
@vishr
vishr deleted the docs/native-port-443 branch November 8, 2026 02:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant