document NETBIRD_DOCKER_SUBNET and the Docker network conflict check - #919
document NETBIRD_DOCKER_SUBNET and the Docker network conflict check#919TechHutTV wants to merge 1 commit into
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughThe self-hosted documentation now explains configurable Docker subnet allocation, derived gateway and Traefik addresses, validation rules, reverse-proxy behavior, and recovery steps for overlapping or stale Docker networks. ChangesDocker subnet documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/pages/selfhosted/enterprise/getting-started.mdx`:
- Line 274: Update the Cause text near the NETBIRD_DOCKER_SUBNET documentation
to replace “fixed subnet” with “default subnet” or “deterministic subnet,” while
preserving the explanation of stable addressing and subnet validation.
In `@src/pages/selfhosted/environment-variables.mdx`:
- Around line 30-32: Qualify the “Before writing any files” statement to apply
only to fresh-install generated files, rather than all scripts. Ensure the
documentation does not imply migrations are side-effect free before the Docker
overlap check; alternatively, document that migrate.sh creates backup/rollback
files and stops old containers first.
In `@src/pages/selfhosted/migration/combined-container.mdx`:
- Around line 213-215: Update the command examples in the migration
documentation, including the rollback command and docker network removal
command, to replace angle-bracket placeholders that shell interprets as
redirection with shell-safe path or variable-style placeholders such as
/path/to/backup-dir/rollback.sh and NETWORK_NAME.
- Around line 177-191: Update
src/pages/selfhosted/migration/combined-container.mdx lines 177-191 to keep both
reverse-proxy trust-pin lists consistent with NETBIRD_DOCKER_SUBNET, or document
the exact manual changes required to replace the old proxy address with the new
Traefik /32. Update src/pages/selfhosted/environment-variables.mdx lines 20-24
to state the migrate.sh exception and link to that manual pin-update procedure.
In `@src/pages/selfhosted/troubleshooting/installation.mdx`:
- Around line 72-76: Update the rerun command in the troubleshooting
installation instructions to match the quickstart’s piped download flow by
setting NETBIRD_DOCKER_SUBNET while downloading and executing getting-started.sh
through the pipe. Do not reference a local ./getting-started.sh file unless the
instructions explicitly add a preceding download step.
- Around line 78-87: Update the Docker network removal command in the
troubleshooting instructions to use the exact network name reported by the
script instead of hard-coding netbird_netbird, and state that the name depends
on the Docker Compose project.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: e4b65c92-0adb-49dd-8827-174593f08daf
📒 Files selected for processing (5)
src/pages/selfhosted/enterprise/getting-started.mdxsrc/pages/selfhosted/environment-variables.mdxsrc/pages/selfhosted/migration/combined-container.mdxsrc/pages/selfhosted/selfhosted-quickstart.mdxsrc/pages/selfhosted/troubleshooting/installation.mdx
| ### Script aborts on a Docker network conflict | ||
|
|
||
| - **Symptom:** The script exits before generating any files, reporting either that an existing Docker network overlaps the subnet NetBird would use, or that the `netbird` network left over from a previous install sits on a different subnet. | ||
| - **Cause:** The stack pins a fixed subnet (`172.30.0.0/24` by default) so Traefik gets a stable address the server can trust. The script checks this up front so you get a clear error instead of a `Pool overlaps with other one on this address space` failure during `docker compose up`. A leftover `netbird` network on a different subnet is also fatal, because Compose would reuse it as-is and the generated configuration would no longer match it. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Use “default” instead of “fixed”.
NETBIRD_DOCKER_SUBNET makes the subnet configurable. The current wording conflicts with the override documented in Line 275. Use “deterministic subnet” or “default subnet”.
🧰 Tools
🪛 LanguageTool
[grammar] ~274-~274: Ensure spelling is correct
Context: ...t so you get a clear error instead of a Pool overlaps with other one on this address space failure duri...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/pages/selfhosted/enterprise/getting-started.mdx` at line 274, Update the
Cause text near the NETBIRD_DOCKER_SUBNET documentation to replace “fixed
subnet” with “default subnet” or “deterministic subnet,” while preserving the
explanation of stable addressing and subnet validation.
| The value must be a `/24` ending in `.0`. `0.0.0.0/8`, `127.0.0.0/8`, `169.254.0.0/16`, `224.0.0.0` and above, and `100.64.0.0/10` are rejected — the last because NetBird assigns overlay peer addresses from that range, so a Docker bridge there would shadow your NetBird network. | ||
|
|
||
| Before writing any files, the scripts check the existing Docker networks and stop with an actionable error if one overlaps the chosen subnet, instead of failing later during `docker compose up`. Existing networks are never modified. Host routes such as LANs and VPN tunnels are not inspected — use this variable if the default range collides with one of those. |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Qualify the “before writing any files” claim.
migrate.sh creates backup and rollback files and stops the old containers before its Docker overlap check. The current sentence applies to all three scripts and can make an aborted migration appear side-effect free. Limit the claim to fresh-install generated files, or document the migration order.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/pages/selfhosted/environment-variables.mdx` around lines 30 - 32, Qualify
the “Before writing any files” statement to apply only to fresh-install
generated files, rather than all scripts. Ensure the documentation does not
imply migrations are side-effect free before the Docker overlap check;
alternatively, document that migrate.sh creates backup/rollback files and stops
old containers first.
| ### Environment variables | ||
|
|
||
| | Variable | Default | Description | | ||
| |---|---|---| | ||
| | `NETBIRD_DOCKER_SUBNET` | `172.30.0.0/24` | The `/24` used for the generated Docker network. Traefik takes `.10` and the gateway `.1`. Must end in `.0`; `0.0.0.0/8`, `127.0.0.0/8`, `169.254.0.0/16`, `224.0.0.0` and above, and `100.64.0.0/10` are rejected. | | ||
|
|
||
| ```bash | ||
| NETBIRD_DOCKER_SUBNET=10.123.45.0/24 ./migrate.sh --install-dir /opt/netbird | ||
| ``` | ||
|
|
||
| Validation runs during preflight, so an invalid value fails before anything on the host is touched. The overlap check against existing Docker networks runs after the old containers are stopped, since `compose down` releases the old deployment's own network first. | ||
|
|
||
| <Note> | ||
| The migration script carries the `reverseProxy` trust pins over from your old `management.json` unchanged. If that configuration already pinned an address inside `172.30.0.0/24`, overriding the subnet will not rewrite the pin — review `config.yaml` after the migration. | ||
| </Note> |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Keep NETBIRD_DOCKER_SUBNET and reverse-proxy trust pins consistent.
The shared reference says the variable derives the pins, but the migration page says migrate.sh preserves old pins. A migrated deployment can therefore place Traefik at <new-subnet>.10 while config.yaml still trusts the old proxy address.
src/pages/selfhosted/migration/combined-container.mdx#L177-L191: Update both trust-pin lists or document the exact manual changes for the new Traefik/32.src/pages/selfhosted/environment-variables.mdx#L20-L24: State themigrate.shexception and link to the manual pin-update procedure.
📍 Affects 2 files
src/pages/selfhosted/migration/combined-container.mdx#L177-L191(this comment)src/pages/selfhosted/environment-variables.mdx#L20-L24
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/pages/selfhosted/migration/combined-container.mdx` around lines 177 -
191, Update src/pages/selfhosted/migration/combined-container.mdx lines 177-191
to keep both reverse-proxy trust-pin lists consistent with
NETBIRD_DOCKER_SUBNET, or document the exact manual changes required to replace
the old proxy address with the new Traefik /32. Update
src/pages/selfhosted/environment-variables.mdx lines 20-24 to state the
migrate.sh exception and link to that manual pin-update procedure.
| ```bash | ||
| bash <backup-dir>/rollback.sh | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Use shell-safe placeholders in the commands.
bash <backup-dir>/rollback.sh and docker network rm <network-name> use shell redirection syntax. Replace them with safe placeholders such as /path/to/backup-dir/rollback.sh and NETWORK_NAME, or show the exact values produced by the script.
Also applies to: 223-227
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/pages/selfhosted/migration/combined-container.mdx` around lines 213 -
215, Update the command examples in the migration documentation, including the
rollback command and docker network removal command, to replace angle-bracket
placeholders that shell interprets as redirection with shell-safe path or
variable-style placeholders such as /path/to/backup-dir/rollback.sh and
NETWORK_NAME.
| **Fix**: For the first error, pick a free `/24` and re-run. The conflicting network belongs to something else, so the script never touches it: | ||
|
|
||
| ```bash | ||
| NETBIRD_DOCKER_SUBNET=10.123.45.0/24 ./getting-started.sh | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Make the rerun command match the installation flow.
The quickstart downloads getting-started.sh through a pipe. It does not create ./getting-started.sh. This command fails unless the user separately downloads the file. Use the same pipe command with NETBIRD_DOCKER_SUBNET, or add a download step.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/pages/selfhosted/troubleshooting/installation.mdx` around lines 72 - 76,
Update the rerun command in the troubleshooting installation instructions to
match the quickstart’s piped download flow by setting NETBIRD_DOCKER_SUBNET
while downloading and executing getting-started.sh through the pipe. Do not
reference a local ./getting-started.sh file unless the instructions explicitly
add a preceding download step.
| For the second error, remove the stale NetBird network and re-run: | ||
|
|
||
| ```bash | ||
| docker network rm netbird_netbird | ||
| ``` | ||
|
|
||
| The subnet must be a `/24` ending in `.0`. See [Installation Script Variables](/selfhosted/environment-variables#installation-script-variables) for the full list of rejected ranges, including `100.64.0.0/10`, which NetBird uses for overlay peer addresses. | ||
|
|
||
| **Confirm**: Re-run the script; it proceeds past the network check and starts provisioning. Verify the result with `docker network inspect <project>_netbird`, which should report the subnet you chose. | ||
|
|
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Use the network name reported by the script.
The command hard-codes netbird_netbird, but Line 86 uses the project-dependent form <project>_netbird. Use the exact network name from the error output and state that the name depends on the Compose project.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/pages/selfhosted/troubleshooting/installation.mdx` around lines 78 - 87,
Update the Docker network removal command in the troubleshooting instructions to
use the exact network name reported by the script instead of hard-coding
netbird_netbird, and state that the name depends on the Docker Compose project.
1 participant
Description
netbirdio/netbird#7073 makes the Compose subnet overridable and adds a fail-fast check for conflicting Docker networks. None of that was documented, so this covers it. It also fixes one page that still presented the subnet as fixed.
The subnet was hardcoded to
172.30.0.0/24acrossgetting-started.sh,getting-started-enterprise.sh, andmigrate.sh. Now you can override it, and the scripts stop with a useful error when something already occupies that range instead of lettingdocker compose upfail later withPool overlaps with other one on this address space. The enterprise stack also picked up a Docker network alias for the public domain.I put the detail on the reference and troubleshooting pages and kept the quickstart short. It only needs the default, the override, and a link out.
Changes
environment-variables.mdx gets a new Installation Script Variables section, which is where I'd point anyone asking about this. It covers the default, the
/24-ending-in-.0requirement, how.1and.10get derived, how the trusted proxy pins stay in step, which ranges get rejected, and the conflict check. I scoped it as a shell variable for the install scripts rather than asetup.envvariable, since the rest of that page is about theconfigure.shflow and I didn't want to blur the two.troubleshooting/installation.mdx gets a section for the conflict error, following the Symptom/Cause/Fix/Confirm pattern already used on that page. Both error variants are quoted word for word so they actually turn up in search. The fix depends on which one you hit: pick a free
/24if an unrelated network is in the way, or remove the stale network if a previous NetBird install left one behind on a different subnet.selfhosted-quickstart.mdx just gets the default, the override one-liner, one sentence about the error, and a link.
migration/combined-container.mdx had a factual problem. It said the generated compose "creates a Docker network (
172.30.0.0/24)" as though that were fixed, so I reworded it and linked the override. I also added an Environment variables subsection under the CLI reference with amigrate.shexample, plus a troubleshooting entry. That last one matters because the overlap check runs after the old containers are already stopped, so the old deployment is down by the time you see the error. The script prints the rollback command and now the docs say so too.enterprise/getting-started.mdx covers the override in 1.2, including the
.envvariables it writes (NETBIRD_NETWORK_SUBNET,NETBIRD_NETWORK_GATEWAY,NETBIRD_TRAEFIK_IP) and a note to change all of them together if you're editing by hand. The Traefik domain alias is documented in 1.6 with the reason behind it. Troubleshooting entry as well.Testing
Checked the behavior against a live install instead of just reading the script. Clean Ubuntu 26.04 box, Docker 29.7.2, Compose v5.4.0, testing the default subnet, an overridden one, all four branches of the conflict check, and the rejected ranges including the
100.64.0.0/10boundary.Related
netbirdio/netbird#7073 is the script change this documents. #626 is the hairpin NAT discussion the enterprise alias came out of.
Summary by CodeRabbit