Repository navigation
docs(deploy): run the native systemd unit on port 443 - #433
Merged
Merged
Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 fanoutdrop-in that:FANOUT_ADDR=:443, which overrides the base unit's loopback address,LoadCredential(%d/...), the same way the guide already handles the auth secret, so the files can stay root-only,CAP_NET_BIND_SERVICEthroughAmbientCapabilities, with a matchingCapabilityBoundingSetandNoNewPrivileges=true. The service still runs as the unprivilegedfanoutuser.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/CapEffshould be0000000000000400, which isCAP_NET_BIND_SERVICEalone), and acurl --resolvereadiness check, with--cacertfor private or Cloudflare Origin CA certificates. It warns that:443binds every interface, so the port should be firewalled to the proxy's networks.No runtime, contract or security behaviour changes.
Verification
systemd-analyze verifywas 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).just site-buildpasses 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, includingscript-tests,lintandtest, on the second run. The first run'sscript-testshit timeouts in the ui-deadcode script tests at ~25–30s per test.ui-testtimed out twice onsrc/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), andui-testpassed on the same base in another branch's run. This PR changes no code.just checkpassed (693s).