From 1480bdba087d8389c8c49fa1c70ab8ece0906a07 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Nov 2026 00:06:59 +0000 Subject: [PATCH] docs: keep the registry mirror reachable only from workspaces MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Short Summary (TL;DR) The documented registry mirror was open to the whole internet, and its UFW rule could not close it. The docs now run the mirror with `--network host` and allow port 5000 only from Docker's addresses. ## The Issue The server setup docs opened port 5000 to everyone with `ufw allow 5000`. The mirror's systemd unit also published the port with `docker run -p 0.0.0.0:5000:5000`. Docker's rules for a published port take effect before UFW's, so even a narrower UFW rule left the mirror open. Anyone could pull images through it, using the host's bandwidth and filling the disk it shares with Coder and the workspaces. Both coder.ddev.com and staging-coder.ddev.com were set up this way, and both mirrors answered requests from outside. ## How This PR Solves The Issue - Step 2's firewall rule allows port 5000 only from `172.16.0.0/12`, Docker's default address range. Workspaces reach the mirror at the host's public name, and the host sees those connections coming from their Docker addresses. - The systemd unit runs the registry with `--network host` instead of publishing the port, so UFW applies to it. - Step 3 explains how to check the host's Docker subnets against that range, and how to fix an existing unit that still uses `-p`. ## Manual Testing Instructions Both hosts already run this configuration. On a host set up this way, from a machine outside it: ```bash curl -s --max-time 5 http://:5000/v2/ || echo blocked ``` Expect `blocked`. Inside a workspace on that host: ```bash docker info | grep -A1 'Registry Mirrors' docker pull hello-world ``` Expect the host's mirror in the list, and a successful pull. ## Automated Testing Overview Claude Code ran markdownlint with `.markdownlint.jsonc` on the changed page, which passed. Nobody ran the strict Zensical build locally, so CI's docs check covers it. Claude Code checked the configuration itself on both hosts: each mirror timed out from the other host, and a workspace on each host still found its mirror and pulled through it. ## Release/Deployment Notes coder.ddev.com and staging-coder.ddev.com already use this configuration. Other self-hosted installs should apply the unit change and the firewall rule from Step 3. 🤖 Developed with assistance from [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01T3Cc2G6867sD8ZdDCVZ7Em --- docs/content/self-hosting/server-setup.md | 25 ++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/docs/content/self-hosting/server-setup.md b/docs/content/self-hosting/server-setup.md index 22e064c..292f088 100644 --- a/docs/content/self-hosting/server-setup.md +++ b/docs/content/self-hosting/server-setup.md @@ -223,13 +223,13 @@ sudo systemctl enable --now docker ### Configure the firewall -Enable UFW and open the ports needed by Coder and the registry mirror. Port 5665 is for the Icinga2 monitoring agent and should be restricted to the monitoring server's IP: +Enable UFW and open the ports needed by Coder and the registry mirror. Port 5665 is for the Icinga2 monitoring agent and should be restricted to the monitoring server's IP. Port 5000 is the registry mirror (Step 3), which only this host's workspaces need, so it allows only Docker's addresses: ```bash sudo ufw allow 22 sudo ufw allow 80 sudo ufw allow 443 -sudo ufw allow 5000 +sudo ufw allow from 172.16.0.0/12 to any port 5000 proto tcp comment 'registry mirror: workspaces only' sudo ufw allow from 45.79.99.253 to any port 5665/tcp sudo ufw enable sudo ufw status @@ -245,12 +245,11 @@ To Action From 443 ALLOW Anywhere 80 ALLOW Anywhere 22 ALLOW Anywhere -5000 ALLOW Anywhere +5000/tcp ALLOW 172.16.0.0/12 # registry mirror: workspaces only 5665/tcp ALLOW 45.79.99.253 443 (v6) ALLOW Anywhere (v6) 80 (v6) ALLOW Anywhere (v6) 22 (v6) ALLOW Anywhere (v6) -5000 (v6) ALLOW Anywhere (v6) ``` --- @@ -301,12 +300,21 @@ proxy: EOF ``` -### Open the firewall port +### Firewall + +The UFW rule from Step 2 allows port 5000 only from `172.16.0.0/12`, Docker's default address range. Workspaces reach the mirror at the host's public name, and the host sees those connections coming from their Docker addresses. Check that every Docker network on the host is inside that range: ```bash -sudo ufw allow 5000/tcp +docker network inspect $(docker network ls -q) --format '{{.Name}} {{range .IPAM.Config}}{{.Subnet}} {{end}}' +grep -A5 default-address-pools /etc/docker/daemon.json ``` +Add a matching `ufw allow from to any port 5000 proto tcp` rule for any subnet outside it. + +Keep the mirror off the public internet. Otherwise anyone can pull images through it, which uses the host's bandwidth and fills the disk it shares with Coder and the workspaces. + +The systemd unit below runs the mirror with `--network host`, so UFW controls port 5000. An older unit that publishes the port with `-p 0.0.0.0:5000:5000` bypasses UFW, because Docker's rules for a published port take effect first. To fix such a unit, replace that line with `--network host`, then run `sudo systemctl daemon-reload` and `sudo systemctl restart registry-mirror`. + ### Create a systemd unit ```bash @@ -324,9 +332,12 @@ RestartSec=5 # Clean up any previous instance ExecStartPre=-/usr/bin/docker rm -f registry-mirror +# --network host, not -p: Docker's rules for a published port take effect +# before UFW's, so a published port 5000 would be open to everyone whatever +# UFW says. ExecStart=/usr/bin/docker run --rm \ --name registry-mirror \ - -p 0.0.0.0:5000:5000 \ + --network host \ -v /opt/registry/config.yml:/etc/distribution/config.yml:ro \ -v /opt/registry/data:/var/lib/registry \ registry:3