Skip to content

docs: keep the registry mirror reachable only from workspaces - #263

Merged
rfay merged 1 commit into
mainfrom
20261118_rfay_registry_mirror_firewall
Nov 18, 2026
Merged

rfay merged 1 commit into
mainfrom
20261118_rfay_registry_mirror_firewall

Conversation

@rfay

@rfay rfay commented Nov 18, 2026

Copy link
Copy Markdown
Member

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:

curl -s --max-time 5 http://<coder-host>:5000/v2/ || echo blocked

Expect blocked. Inside a workspace on that host:

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.ai/code/session_01T3Cc2G6867sD8ZdDCVZ7Em

## 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://<coder-host>: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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T3Cc2G6867sD8ZdDCVZ7Em
@read-the-docs-community

Copy link
Copy Markdown

Documentation build overview

📚 coder-ddev | 🛠️ Build #35970769 | 📁 Comparing 1480bdb against latest (7cdac4e)

  🔍 Preview build  

1 file changed
± self-hosting/server-setup/index.html

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Previews

The start.coder.ddev.com landing-page preview has been removed. Read the Docs keeps or removes its own docs preview.

@rfay
rfay merged commit 7375724 into main Nov 18, 2026
8 checks passed
@rfay
rfay deleted the 20261118_rfay_registry_mirror_firewall branch November 18, 2026 00:11
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.

2 participants