docs: add documentation for non-root container images and security considerations

[ryan-steed-usa]

Documentation should have been included with #368 or #412.

Summary by CodeRabbit

• Documentation
  • Clarified README wording (minor punctuation) for local OpenAI-compatible server guidance.
  • Updated Docker install notes to document non-root image variants for improved security and added an example non-root CUDA tag.
  • Added a new Container Security section describing root vs non-root images, host permission considerations, and Docker/Podman mapping guidance for safer deployments.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Added documentation for non-root Docker image variants and a new Container Security page explaining root vs non-root image behavior, host resource/permission considerations, and namespace mapping options (Docker/Podman).

Changes

Cohort / File(s)	Summary
Docs: README update README.md	Updated Docker install line to mention non-root image variants (examples with *-non-root), added non-root CUDA tag reference (cuda-non-root), adjusted punctuation, and linked to container security guidance.
Docs: New container security doc docs/container-security.md	Added new documentation describing default root behavior of images, availability and trade-offs of non-root image variants, host permission and group-mapping considerations, Docker user namespace remapping and Podman UID/GID mapping, and guidance on planning for non-root usage.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

• Doc-only changes; focus review on wording and example image tags in README.md and accuracy/clarity in docs/container-security.md.

Possibly related PRs

• feat: build both root and non-root container images #412: Related — documents and examples reference newly added non-root image variants introduced in that PR.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main changes: adding documentation for non-root container images and security considerations, which matches the README updates and new docs/container-security.md file.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6ba0cc3 and 24e98df.

📒 Files selected for processing (2)

• README.md (3 hunks)
• docs/container-security.md (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/container-security.md

🧰 Additional context used

🧠 Learnings (3)

📓 Common learnings

Learnt from: ryan-steed-usa
Repo: mostlygeek/llama-swap PR: 368
File: docker/llama-swap.Containerfile:14-20
Timestamp: 2025-10-27T16:04:23.381Z
Learning: In docker/llama-swap.Containerfile, the user/group creation logic intentionally supports adding a non-root user (non-zero UID) to the root group (GID=0) as a valid configuration. This allows flexible UID/GID customization where users can specify only a UID or both UID and GID.

📚 Learning: 2025-11-08T16:56:35.626Z

Learnt from: ryan-steed-usa
Repo: mostlygeek/llama-swap PR: 391
File: docker/build-container.sh:29-32
Timestamp: 2025-11-08T16:56:35.626Z
Learning: In the mostlygeek/llama-swap repository, llama.cpp container tags from ghcr.io/ggml-org/llama.cpp use build identifiers (e.g., `b6981`) rather than semantic versions. The tag format is `server-<something>-<build-id>` for cpu and `server-<arch>-<something>-<build-id>` for other architectures, where extracting the third field with `awk -F '-' '{print $3}'` correctly retrieves the build identifier.

Applied to files:

• README.md

📚 Learning: 2025-10-27T16:04:23.381Z

Learnt from: ryan-steed-usa
Repo: mostlygeek/llama-swap PR: 368
File: docker/llama-swap.Containerfile:14-20
Timestamp: 2025-10-27T16:04:23.381Z
Learning: In docker/llama-swap.Containerfile, the user/group creation logic intentionally supports adding a non-root user (non-zero UID) to the root group (GID=0) as a valid configuration. This allows flexible UID/GID customization where users can specify only a UID or both UID and GID.

Applied to files:

• README.md

🪛 LanguageTool

README.md

[grammar] ~16-~16: Use a hyphen to join words.
Context: ...model switching - ✅ Use any local OpenAI compatible server (llama.cpp, vllm, tabb...

(QB_NEW_EN_HYPHEN)

🔇 Additional comments (2)

README.md (2)

92-93: Non-root example is well-placed and helpful.

The new example demonstrates how to pull the non-root cuda variant and complements the documentation updates on line 64. Users looking at Docker examples will now easily discover the non-root option.

---

64-64: Documentation update appropriately references non-root variants and security.

The change clearly communicates that non-root variants are available and links to detailed security documentation at docs/container-security.md. This directly supports the PR objective.

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b1dec8b and 9e4b266.

📒 Files selected for processing (1)

• README.md (3 hunks)

🧰 Additional context used

🧠 Learnings (3)

📓 Common learnings

Learnt from: ryan-steed-usa
Repo: mostlygeek/llama-swap PR: 368
File: docker/llama-swap.Containerfile:14-20
Timestamp: 2025-10-27T16:04:23.381Z
Learning: In docker/llama-swap.Containerfile, the user/group creation logic intentionally supports adding a non-root user (non-zero UID) to the root group (GID=0) as a valid configuration. This allows flexible UID/GID customization where users can specify only a UID or both UID and GID.

📚 Learning: 2025-10-27T16:04:23.381Z

Learnt from: ryan-steed-usa
Repo: mostlygeek/llama-swap PR: 368
File: docker/llama-swap.Containerfile:14-20
Timestamp: 2025-10-27T16:04:23.381Z
Learning: In docker/llama-swap.Containerfile, the user/group creation logic intentionally supports adding a non-root user (non-zero UID) to the root group (GID=0) as a valid configuration. This allows flexible UID/GID customization where users can specify only a UID or both UID and GID.

Applied to files:

• README.md

📚 Learning: 2025-11-08T16:56:35.626Z

Learnt from: ryan-steed-usa
Repo: mostlygeek/llama-swap PR: 391
File: docker/build-container.sh:29-32
Timestamp: 2025-11-08T16:56:35.626Z
Learning: In the mostlygeek/llama-swap repository, llama.cpp container tags from ghcr.io/ggml-org/llama.cpp use build identifiers (e.g., `b6981`) rather than semantic versions. The tag format is `server-<something>-<build-id>` for cpu and `server-<arch>-<something>-<build-id>` for other architectures, where extracting the third field with `awk -F '-' '{print $3}'` correctly retrieves the build identifier.

Applied to files:

• README.md

🪛 LanguageTool

README.md

[style] ~64-~64: In American English, abbreviations like “etc.” require a period.
Context: ...ultiple platforms (cuda, vulkan, intel, etc) including non-root variants. ```shell...

(ETC_PERIOD)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: run-tests

🔇 Additional comments (2)

README.md (2)

92-94: Non-root image variant example is clear and helpful.

The addition of the non-root cuda image example effectively demonstrates how to access the alternative images referenced in the updated Docker installation note.

---

223-231: Container Security section provides balanced, practical guidance.

The new section effectively communicates the security tradeoff between root-user convenience and attack surface reduction. The documentation correctly identifies that non-root alternatives are available, acknowledges that additional configuration may be necessary (aligning with the flexible UID/GID customization in the Dockerfile), and references Docker and Podman's respective user namespace features as mitigation strategies.

The framing that "proper planning and configuration is recommended" appropriately positions non-root images as a security improvement without overstating their value, while contextualizing the LLM ecosystem's emerging security concerns.

Please verify that the external documentation links remain current:

• Docker user namespace remapping documentation
• Podman UID/GID mapping documentation
• HuggingFace security documentation

You may also want to confirm that the non-root image tag examples (e.g., llama-swap:cpu-non-root) match the actual available tags in the container registry.

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 9e4b266 and c00de9c.

📒 Files selected for processing (1)

• README.md (4 hunks)

🧰 Additional context used

🧠 Learnings (3)

📓 Common learnings

Learnt from: ryan-steed-usa
Repo: mostlygeek/llama-swap PR: 368
File: docker/llama-swap.Containerfile:14-20
Timestamp: 2025-10-27T16:04:23.381Z
Learning: In docker/llama-swap.Containerfile, the user/group creation logic intentionally supports adding a non-root user (non-zero UID) to the root group (GID=0) as a valid configuration. This allows flexible UID/GID customization where users can specify only a UID or both UID and GID.

📚 Learning: 2025-10-27T16:04:23.381Z

Learnt from: ryan-steed-usa
Repo: mostlygeek/llama-swap PR: 368
File: docker/llama-swap.Containerfile:14-20
Timestamp: 2025-10-27T16:04:23.381Z
Learning: In docker/llama-swap.Containerfile, the user/group creation logic intentionally supports adding a non-root user (non-zero UID) to the root group (GID=0) as a valid configuration. This allows flexible UID/GID customization where users can specify only a UID or both UID and GID.

Applied to files:

• README.md

📚 Learning: 2025-11-08T16:56:35.626Z

Learnt from: ryan-steed-usa
Repo: mostlygeek/llama-swap PR: 391
File: docker/build-container.sh:29-32
Timestamp: 2025-11-08T16:56:35.626Z
Learning: In the mostlygeek/llama-swap repository, llama.cpp container tags from ghcr.io/ggml-org/llama.cpp use build identifiers (e.g., `b6981`) rather than semantic versions. The tag format is `server-<something>-<build-id>` for cpu and `server-<arch>-<something>-<build-id>` for other architectures, where extracting the third field with `awk -F '-' '{print $3}'` correctly retrieves the build identifier.

Applied to files:

• README.md

🪛 LanguageTool

README.md

[grammar] ~16-~16: Use a hyphen to join words.
Context: ...model switching - ✅ Use any local OpenAI compatible server (llama.cpp, vllm, tabb...

(QB_NEW_EN_HYPHEN)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: run-tests

🔇 Additional comments (3)

README.md (3)

64-64: Punctuation corrected.

The "etc.)" punctuation has been properly applied. LGTM.

---

92-93: Clear non-root image example.

The added non-root image pull example is practical and helps users quickly find non-root variants.

---

223-231: Well-structured security section with appropriate tradeoff guidance.

The new Container Security section clearly explains the root-vs.-non-root tradeoff, references relevant Docker and Podman documentation, and acknowledges LLM ecosystem vulnerabilities. The recommendation to plan and configure appropriately is sound.

One minor verification: Line 227 states the non-root variant uses the "app" user by default. Please confirm this matches the actual user configured in the non-root container image builds (e.g., in docker/llama-swap.Containerfile or related build scripts), so documentation and implementation remain synchronized.