docs: Cleaned up container document - #2197
Conversation
Added more explicit explanation to some items Added note on Global State Policies and container networks about accept-invalid Changed Zabbix configuration example because it used port publishing which can't be used with container networks Added Adguard Home configuration example
|
All contributors have signed the CLA ✍️ ✅ |
|
I have read the CLA Document and I hereby sign the CLA |
|
Claude finished @Diekos's task in 3m 58s —— View job Review completeReviewed against IssuesERROR —
WARNING —
INFO — typo Needs Verification
False positives from Pass 1All four HIGH-confidence Pass 1 findings were pattern-parser artifacts (bracketed value-lists like
Stats
|
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited) Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
🔗 Linked repositories identifiedCodeRabbit considers these linked repositories for cross-repo context during reviews:
🚧 Files skipped from review as they are similar to previous changes (1)
📜 Recent review details⏰ Context from checks skipped due to timeout. (3)
🧰 Additional context used🔍 Remote MCP vyos.devRelevant review context
📝 WalkthroughSummary by CodeRabbit
WalkthroughThe container documentation separates configuration commands, clarifies networking and storage, documents operation commands and ARP firewall handling, and adds static-address destination-NAT examples for Zabbix and AdGuard Home. ChangesContainer documentation
Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches✨ Simplify code
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 |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
🤖 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 `@docs/configuration/container/index.md`:
- Around line 478-481: Update NAT destination rule 101’s translation address to
172.20.0.13 so HTTP traffic targets the zabbix-web-nginx-mysql container, while
preserving its existing port, protocol, and translation-port settings.
- Around line 448-449: Update the mysql-server environment variable examples for
MYSQL_PASSWORD and MYSQL_ROOT_PASSWORD to use clearly marked placeholder values,
and add a note instructing operators to replace them with unique secrets before
deployment.
- Around line 409-412: Update the description for the `show container network`
operation to read “Show a list of available container networks,” adding the
missing preposition while preserving the existing wording.
- Around line 436-437: Update the Zabbix and AdGuard Home prose links to
reference-style links, using the exact “AdGuard Home” capitalization. Keep
canonical documentation lines under 80 characters, and wrap only any overlong
reference definitions with paired “% stop_vyoslinter” and “% start_vyoslinter”
markers.
- Around line 496-499: Update the note text in the AdGuard Home configuration
example to use “built-in DNS forwarder” and replace the comma splice after the
container port explanation with two separate sentences.
- Line 208: Update the source description in the container configuration
documentation to correct the typo, changing “iself” to “itself” while leaving
the rest of the text unchanged.
- Around line 282-283: Wrap the firewall note in
docs/configuration/container/index.md so every source line is at most 80
characters, and remove trailing whitespace from the affected lines while
preserving the existing wording and formatting.
🪄 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: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)
Review profile: CHILL
Plan: Pro Plus
Run ID: fa3d2867-60fa-44c1-bd4b-8e7178fea239
📒 Files selected for processing (1)
docs/configuration/container/index.md
🔗 Linked repositories identified
CodeRabbit considers these linked repositories for cross-repo context during reviews:
ansible/ansible(manual)
📜 Review details
⏰ Context from checks skipped due to timeout. (3)
- GitHub Check: validate
- GitHub Check: Mergify Merge Protections
- GitHub Check: Summary
🧰 Additional context used
📓 Path-based instructions (2)
docs/**/*.md
📄 CodeRabbit inference engine (AGENTS.md)
docs/**/*.md: Canonical docs pages must be written as MyST Markdown (.md); edit existing pages in.mdonly and never use the oldmd-prefix for new pages.
Use{cfgcmd},{opcmd}, and{cmdincludemd}fenced directives in MyST pages for VyOS command coverage; do not replace them with plaintextorbashfences.
Use MyST ATX headings (#,##,###, etc.) in canonical pages; the RST heading hierarchy does not apply to.mdsources.
In MyST pages, prefer single backticks for inline code; double backticks are reserved for embedded RST contexts.
Use% stop_vyoslinterand% start_vyoslintercomment markers in top-level MyST content to suppress real IPs or other allowed long-line exceptions, and keep them paired.
In MyST pages, write TODO markers as{todo}fenced directives.
Files:
docs/configuration/container/index.md
docs/{_include/*.txt,**/*.md}
📄 CodeRabbit inference engine (AGENTS.md)
Keep documentation lines within 80 characters unless the content is inside a code block or fenced/preformatted block.
Files:
docs/configuration/container/index.md
🧠 Learnings (13)
📚 Learning: 2026-05-06T20:48:49.689Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:71-71
Timestamp: 2026-05-06T20:48:49.689Z
Learning: In vyos/vyos-documentation, the 80-character line-length rule documented under Source conventions / Formatting applies only to documentation source files located under docs/ (e.g., docs/**/*.rst and docs/**/*.md). The rule is enforced by the vyoslinter (doc-linter.py from vyos/.github) when reviewing changed files via lint-doc.yml, and only for files within docs/**. Do not suggest hard-wrapping CLAUDE.md (repo-root documentation) because GitHub renders and reflows content. For CLAUDE.md, reviews should not enforce the 80-char wrapping; apply the rule only to files matching **/docs/**/*.{rst,md}.
Applied to files:
docs/configuration/container/index.md
📚 Learning: 2026-05-06T20:48:57.970Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:91-93
Timestamp: 2026-05-06T20:48:57.970Z
Learning: The 80-character line limit applies only to documentation sources under docs/** (RST/MD). Do not enforce this limit on repo-root Markdown files like CLAUDE.md or README.md. The vyoslinter (doc-linter.py, run via lint-doc.yml from vyos/.github) lints only changed files within docs/**; root files are excluded. GitHub renders root Markdown with viewport-width reflow, so hard-wrapping these files reduces readability without tooling benefit.
Applied to files:
docs/configuration/container/index.md
📚 Learning: 2026-05-06T20:48:50.446Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:64-64
Timestamp: 2026-05-06T20:48:50.446Z
Learning: Enforce the 80-character line-length limit only for documentation source files under docs/ (docs/**/*.md and docs/**/*.rst rendered by Sphinx and linted by vyoslinter via lint-doc.yml). Do not flag line-length issues in repository-root Markdown files such as CLAUDE.md or README.md, which GitHub renders with viewport-width reflow. This applies to all files within docs/ that are part of the documentation source.
Applied to files:
docs/configuration/container/index.md
📚 Learning: 2026-05-06T20:48:54.578Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:80-84
Timestamp: 2026-05-06T20:48:54.578Z
Learning: Enforce the 80-character line-length limit only for documentation source files under docs/ (docs/**/*.rst and docs/**/*.md). Do not flag repo-root files like CLAUDE.md or README.md, since they are rendered by GitHub and not subject to this rule. The doc-linter (doc-linter.py via lint-doc.yml) only lints docs/**, so CI checks won't flag root files for line length.
Applied to files:
docs/configuration/container/index.md
📚 Learning: 2026-05-06T20:49:00.044Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:108-108
Timestamp: 2026-05-06T20:49:00.044Z
Learning: Limit the 80-character line length check and vyoslinter (doc-linter.py) enforcement to documentation source files under docs/**/*.{rst,md}. Do not apply or flag line-length issues in repo-root files like CLAUDE.md or README.md, which are rendered directly by GitHub and are not linted by lint-doc.yml. This pattern narrows checks to Sphinx source docs and prevents false positives in non-doc files.
Applied to files:
docs/configuration/container/index.md
📚 Learning: 2026-05-06T20:48:53.302Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:79-79
Timestamp: 2026-05-06T20:48:53.302Z
Learning: Limit line length to 80 characters only for documentation sources under the docs directory (docs/**/*.rst and docs/**/*.md). This is enforced by the vyoslinter doc-linter.py (from the vyos/.github repo) via lint-doc.yml on changed files under docs/**. Do not flag line-length violations in repository-root Markdown files like CLAUDE.md or README.md, as they are rendered by GitHub and reflow in the UI.
Applied to files:
docs/configuration/container/index.md
📚 Learning: 2026-05-06T20:49:10.359Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:142-142
Timestamp: 2026-05-06T20:49:10.359Z
Learning: In vyos/vyos-documentation, the 80-character line limit and vyoslinter enforcement apply only to documentation source files under docs/**/*.rst and docs/**/*.md that Sphinx renders. Repo-root files such as CLAUDE.md and README.md are outside the linter's scope (lint-doc.yml runs on docs/**) and are rendered by GitHub with automatic paragraph reflow — do not flag line-length violations in these files.
Applied to files:
docs/configuration/container/index.md
📚 Learning: 2026-05-06T20:49:15.361Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:163-163
Timestamp: 2026-05-06T20:49:15.361Z
Learning: In vyos/vyos-documentation, enforce the 80-character line-length limit (Source conventions / Formatting) only for Sphinx documentation source files under docs/**/*.rst and docs/**/*.md. The lint-doc.yml workflow runs the doc-linter (doc-linter.py) and checks only docs/** changed files. Files in the repository root (e.g., CLAUDE.md, README.md) are rendered by GitHub and are not subject to this rule; do not flag line-length violations in those files.
Applied to files:
docs/configuration/container/index.md
📚 Learning: 2026-05-08T07:01:22.978Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1878
File: docs/troubleshooting/connectivity.rst:0-0
Timestamp: 2026-05-08T07:01:22.978Z
Learning: For the VyOS documentation (MyST-based docs), MyST directive opener lines must keep the entire directive arguments on a single line. This includes MyST fenced-directive openers like ```{opcmd} ... ``` and the RST-equivalent form .. opcmd:: ... when ported/used in MyST. Because the MyST parser does not support wrapped/continued directive arguments across multiple lines, do not raise/keep review warnings suggesting line wrapping for these directive opener lines due to line-length (even if they exceed 80 characters).
Applied to files:
docs/configuration/container/index.md
📚 Learning: 2026-05-08T07:01:22.978Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1878
File: docs/troubleshooting/connectivity.rst:0-0
Timestamp: 2026-05-08T07:01:22.978Z
Learning: In vyos/vyos-documentation, do not raise line-length (>80 chars) review findings for MyST directive opener lines (the directive “opener” that uses MyST directive syntax such as `{cfgcmd}` / `{opcmd}` fence/openers). CI does not enforce the 80-character limit for these specific opener lines, and existing documentation contains longer opener lines that pass lint.
Applied to files:
docs/configuration/container/index.md
📚 Learning: 2026-05-13T22:16:06.198Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 2021
File: docs/automation/terraform/terraformvyos.md:14-14
Timestamp: 2026-05-13T22:16:06.198Z
Learning: In the vyos/vyos-documentation repo, when a PR is a byte-for-byte documentation port of an existing file from the rolling branch to a release branch (e.g., circinus, sagitta), keep the port content identical to the production-tested rolling source. For these ports, do not raise new review findings for documentation issues that are already present in the rolling source (for example, markdownlint MD059 like non-descriptive link text such as `[link]`/`[install]`). Instead, defer those existing issues to a rolling-side cleanup PR (e.g., `#2024`) and then backport the cleanup via Mergify.
Applied to files:
docs/configuration/container/index.md
📚 Learning: 2026-05-13T22:43:41.056Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 2024
File: docs/automation/terraform/terraformvyos.md:0-0
Timestamp: 2026-05-13T22:43:41.056Z
Learning: In docs/**/*.md, for Markdown reference definition lines of the form `[label]: <URL>`, if the line cannot be shortened to <= 80 characters (because the URL itself is near/at the limit), suppress the vyoslinter warning by wrapping only that reference definition with a `% stop_vyoslinter` / `% start_vyoslinter` block. If the reference definition can fit within 80 characters, leave it outside any suppression block.
Applied to files:
docs/configuration/container/index.md
📚 Learning: 2026-06-05T19:21:44.474Z
Learnt from: LiudmylaNad
Repo: vyos/vyos-documentation PR: 2066
File: docs/configuration/protocols/traffic-engineering.md:0-0
Timestamp: 2026-06-05T19:21:44.474Z
Learning: In the vyos/vyos-documentation MyST documentation pages, when writing CLI example invocations directly under a `{cfgcmd}` directive, use `none` fenced code blocks for those examples. Do not change these example blocks to `{opcmd}` or `{cfgcmd}`—`{opcmd}` is reserved for operational-mode commands, and the surrounding `{cfgcmd}` directive already documents the target command. Plain `none` blocks for these CLI examples are intentional and correct.
Applied to files:
docs/configuration/container/index.md
🪛 LanguageTool
docs/configuration/container/index.md
[grammar] ~498-~498: Use a hyphen to join words.
Context: ...rt 53 if you don't want to use the built in dns forwarder ::: ```none set contain...
(QB_NEW_EN_HYPHEN)
🔍 Remote MCP Context7, vyos.dev
Relevant review context
- VyOS documentation explicitly states that port publishing is incompatible with user-defined container networks; the supported workaround is static container addressing plus destination NAT. The first network IP is reserved by the engine.
- T6793, “Firewall Blocking ARP from Podman Container to Gateway,” was resolved after confirming this command fixes container ARP:
set firewall global-options apply-to-bridged-traffic accept-invalid ethernet-type arp., - Related open reports document failures when combining custom container networks, port mappings, and VRFs:
- T9142 remains open and reports that the current
accept-invalid dhcphandling accepts DHCP replies but not requests; avoid implying that this exception universally resolves bridged DHCP. - T9120, “Docs structural improvements (8 items, KB-independent),” explicitly identifies the container documentation monolith for restructuring, aligning with this cleanup.
No T-number appears in the supplied PR context itself, so no task could be treated as the PR’s authoritative objective.
🔇 Additional comments (2)
docs/configuration/container/index.md (2)
73-73: LGTM!Also applies to: 122-143
383-384: LGTM!Also applies to: 393-408, 414-423, 464-469, 487-492, 500-524
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Review in progress
|
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Review in progress
|
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
|
Claude Code is working… I'll analyze this and get back to you. |
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Review in progress
|
Review in progress
|
|
Claude finished @Diekos's task in 3m 37s —— View job Review completeReviewed against IssuesERROR —
WARNING —
INFO — Dangling promise: "create the necessary directories from a shell" (inline comment on line 491)
Needs Verification
False positives from Pass 1All four HIGH-confidence Pass 1 findings were pattern-parser artifacts (bracketed value-lists like
Stats
|
Diekos
changed the title
|
Claude finished @Diekos's task in 2m 43s —— View job Review completeReviewed against IssuesRESOLVED since previous review
WARNING —
INFO — Dangling shell-command promise (unchanged since previous review)
Needs Verification
False positives from Pass 1All three HIGH-confidence Pass 1 findings were pattern-parser artifacts (bracketed value-lists like
Stats
|
wording around directories.
|
Claude finished @Diekos's task in 1m 40s —— View job Review completeReviewed against IssuesRESOLVED since previous review
Needs Verification (unchanged since previous review — carrying forward)
False positives from Pass 1All three HIGH-confidence Pass 1 findings are pattern-parser artifacts (bracketed value-lists like
Stats
|
There was a problem hiding this comment.
Pull request overview
This PR refines the VyOS container documentation page by clarifying several container configuration options and expanding the examples section (notably around container networks and service exposure).
Changes:
- Improves explanations for port publishing, volume mounts, device mappings, and logging defaults.
- Adds a note about Global State Policies when using container networks and updates the Zabbix example to use DNAT instead of port publishing.
- Adds an AdGuard Home example configuration.
Suppressed comments (5)
docs/configuration/container/index.md:204
- The
cfgcmdfence for the devicesourcecommand is missing its closing ``` delimiter. As written, thedestinationcommand line is nested as literal text inside the `source` directive.
```{cfgcmd} set container name \<name\> device \<devicename\> source \<path\>
docs/configuration/container/index.md:138
- The
cfgcmdfence for the volumesourcecommand is missing its closing ``` delimiter, so the subsequentdestination`cfgcmd` line is treated as literal text inside the first directive instead of a separate directive.
```{cfgcmd} set container name \<name\> volume \<volumename\> source \<path\>
docs/configuration/container/index.md:168
- The
cfgcmdfence for theuidcommand is missing its closing ``` delimiter, which causes thegiddirective to be parsed as plain text inside the `uid` block.
```{cfgcmd} set container name \<name\> uid \<number\>
docs/configuration/container/index.md:338
- The
cfgcmdfence forauthentication usernameis missing its closing ``` delimiter, which causes theauthentication passworddirective to be treated as plain text inside the username block.
```{cfgcmd} set container registry \<name\> authentication username
docs/configuration/container/index.md:358
- The
cfgcmdfences formirror address,mirror host-name, andmirror portare missing their closing ``` delimiters. This nests subsequentcfgcmdlines as literal text inside the first directive and can break how these commands are indexed/linked in the rendered docs.
```{cfgcmd} set container registry \<name\> mirror address \<address\>
```{cfgcmd} set container registry \<name\> mirror host-name \<host-name\>
```{cfgcmd} set container registry \<name\> mirror port \<port\>
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| ``` | ||
|
|
||
| ```{cfgcmd} set container name \<name\> health-check retries \<retries\> | ||
| ```{cfgcmd} set container name \<name\> health-check retry \<retries\> |
There was a problem hiding this comment.
On my router running VyOS 2026.08.05-0033-rolling, it is "retry":
vyos@VYOS01# set container name dns health-check
Possible completions:
command Health check command to run for the container
interval Overwrite related health check configuration from the image
retry The number of retries before container is consider unhealthy
timeout Timeout for the health check to complete
[edit]
vyos@VYOS01# set container name dns health-check
Fixed fences
|
Claude finished @Diekos's task in 2m 6s —— View job Review completeReviewed against IssuesERROR — stray prompt/review text pasted into the container-registry description (new regression in commit
WARNING — Zabbix intro sentence is grammatically incomplete (pre-existing, but the PR reworded the tail) (inline comment posted on lines 438–439)
Resolved since previous review
Needs Verification (carrying forward from previous reviews)
False positives from Pass 1All three HIGH-confidence Pass 1 findings are pattern-parser artifacts (bracketed value-lists like
Stats
|
No idea how that ended up in the file. Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
|
Claude finished @Diekos's task in 2m 9s —— View job Review completeReviewed against Resolved since previous review
IssuesWARNING — Zabbix intro sentence is still grammatically incomplete (carried over from previous review)
Needs Verification (carrying forward from previous reviews)
False positives from Pass 1All three HIGH-confidence Pass 1 findings are pattern-parser artifacts (bracketed value-lists like
Stats
|
|
Claude finished @Diekos's task in 1m 42s —— View job Review completeReviewed against Resolved since previous review
No new commits touched other files. All remaining items below are carried over from prior reviews. IssuesNo confirmed new issues in commit Needs Verification (carrying forward from previous reviews)
False positives from Pass 1All three HIGH-confidence Pass 1 findings are pattern-parser artifacts (bracketed value-lists like
Stats
|
Change Summary
Cleaned up container document
Added more explicit explanation to some items
Added note on Global State Policies and container networks about accept-invalid
Changed Zabbix configuration example because it used port publishing which can't be used with container networks
Added Adguard Home configuration example
Related Task(s)
Related PR(s)
Backport
Checklist: