DEP-91: document Hoop container image options by racerxdl · Pull Request #156 · hoophq/documentation

racerxdl · 2026-08-04T18:06:31Z

Summary

explain the gateway, standard agent, minimal agent, clean-line, and OCR image roles
document safe Helm selection, migration requirements, tags, and update cadence
add the image guide to deployment navigation and overview

Dependency

This documentation is only meaningful after the DEP-91 stack in hoophq/hoop is merged and its image and Helm changes are available: hoophq/hoop#1683, hoophq/hoop#1684, hoophq/hoop#1685, hoophq/hoop#1686, hoophq/hoop#1687, hoophq/hoop#1688, hoophq/hoop#1689.

The hoophq/hoopdev-minimal image and the image.minimal Helm toggle described here ship in hoophq/hoop#1685. (That stack replaces the original hoophq/hoop#1662, which was split for reviewability.) Keep this PR blocked until at least hoophq/hoop#1685 lands.

How to test

Setup

npm ci
npm run dev

Steps

Open http://localhost:3000/setup/deployment/overview.
- Expected: a Choose container images section links to the new guide.
Open the guide from that link.
- Expected: the page renders under Deployment → Container Images and covers hoop, hoop-ng, hoopdev, hoopdev-minimal, hoopdev-ng, and the CPU/GPU OCR image.
Review the minimal and clean-line guidance.
- Expected: minimal is described as the low-dependency bring-your-own-tools option; -ng is described as the broad-toolkit AGPL/SSPL-free line. Clean Helm values are nested under hoop-chart or hoopagent-chart, and upgrades preserve the existing namespace.
Review the OCR safety guidance.
- Expected: it warns that changing only the stock chart image is unsupported, requires command: ["hoop", "start", "agent"], and uses the Presidio service on port 3000.

Link check

npx mint broken-links

Expected: no new broken link originates from this change. The repository currently reports the pre-existing concepts/agents.mdx link to /api-reference.

Automated by MisterMal

Document gateway and agent image roles, safe selection criteria, Helm migration requirements, and image tag policy. Fixes #DEP-91 🤖 Generated with Mister Maluco Co-Authored-By: MisterMal <teskeslab@lucasteske.dev>

mintlify · 2026-08-04T18:06:34Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
hoopdev	🟢 Ready	View Preview	Aug 4, 2026, 6:08 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

netlify · 2026-08-04T18:06:37Z

✅ Deploy Preview for decap-documentation ready!

Name	Link
🔨 Latest commit	`aa561fd`
🔍 Latest deploy log	https://app.netlify.com/projects/decap-documentation/deploys/6a722dc12460ab0008594fb9
😎 Deploy Preview	https://deploy-preview-156--decap-documentation.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

qodo-code-review · 2026-08-04T18:09:10Z

PR Summary by Qodo

Document Hoop gateway and agent container image options

📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Add a Deployment guide explaining gateway vs agent image roles and safe selection.
• Document minimal, clean (-ng), and OCR agent tradeoffs, Helm migration, and tag policy.
• Link the new guide from Deployment overview and navigation.

Diagram

graph TD
  A["Deployment Overview"] --> B["Container Images Guide"] --> C(["Gateway images"]) --> D(["Agent images"]) --> E{"Helm chart choice"} --> F["Presidio deploy doc"]
  D -. "RDP PII guard" .-> F
  subgraph Legend
    direction LR
    _page["Doc page"] ~~~ _img(["Image/repo"]) ~~~ _dec{"Decision"}
  end

High-Level Assessment

The PR’s approach (a single canonical “Container Images” guide linked from Deployment Overview and nav) is the clearest way to centralize image-line selection, Helm migration caveats, and OCR safety constraints without scattering cross-references across multiple deployment pages.

Files changed (3) +184 / -0

Documentation (2) +183 / -0

container-images.mdxNew guide for gateway/agent image lines, Helm migration, and tag policy +179/-0

New guide for gateway/agent image lines, Helm migration, and tag policy

• Introduces a comprehensive container image selection guide: explains gateway vs agent roles, compares standard vs minimal vs clean (-ng) lines, and documents the OCR agent constraints and required runtime settings. Adds operational guidance on Helm wrapper chart values nesting/migration and image tag/update/digest pinning policy.

setup/deployment/container-images.mdx

overview.mdxLink Deployment overview to the container image guide +4/-0

Link Deployment overview to the container image guide
• Adds a new “Choose container images” section that directs self-hosted users to the container image guide and summarizes the major image options.
setup/deployment/overview.mdx

Other (1) +1 / -0

docs.jsonAdd Container Images page to Deployment navigation +1/-0

Add Container Images page to Deployment navigation
• Registers the new container-images guide in the Deployment section so it appears in site navigation.
docs.json

qodo-code-review · 2026-08-04T18:12:43Z

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

Context used

✅ Tickets:

🎫 [Feature]: hoophq/hoopdev base image carries 1,000+ fixable CVEs; request slimmer agent image and dependency refresh

✅ Compliance rules (platform): 11 rules

✅ Cross-repo context

Explored: repo: hoophq/hoop (branch: dep-91, sha: 5d3dd9cc)

Not relevant to this PR: hoophq/changelog

1. ~~K8s OCR entrypoint bypass~~ ✓ Resolved 🔗 Cross-repo conflict ≡ Correctness

Description

The new guide tells Kubernetes users of hoophq/hoop-agent-ocr to set container `command:
["hoop","start","agent"], but in Kubernetes command` overrides the image ENTRYPOINT that starts
the bundled OCR server. Because the OCR image’s ENTRYPOINT is responsible for starting OCR and then
running the agent command, this guidance can deploy an agent without OCR (breaking realtime RDP PII
guarding) unless you use args or otherwise preserve the ENTRYPOINT defined in hoophq/hoop.

Code

setup/deployment/container-images.mdx[162]

+For Kubernetes, set the same `command` and environment variables in the container specification and source `HOOP_KEY` from a Secret.

Relevance

●● Moderate
Technically plausible but depends on actual image entrypoint/Helm behavior; no close repo precedent
found.
ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The PR explicitly tells Kubernetes users to set command, while the hoophq/hoop OCR image sets an
ENTRYPOINT that must run to start the embedded OCR server; the ENTRYPOINT script then runs the
passed command via "$@", which will be skipped if Kubernetes replaces ENTRYPOINT via command.
setup/deployment/container-images.mdx[149-163]
External repo: hoophq/hoop, Dockerfile.agent-ocr [62-66]
External repo: hoophq/hoop, scripts/dev/ocr-poc/entrypoint-embedded.sh [41-67]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The docs instruct Kubernetes users to set `command: ["hoop", "start", "agent"]` for the `hoophq/hoop-agent-ocr` image.

In Kubernetes, `command` overrides the image ENTRYPOINT, but the OCR image’s ENTRYPOINT is what starts the bundled OCR service and then executes the provided CMD/args. Overriding `command` therefore bypasses OCR startup.

## Issue Context
- Docker Compose `command` typically overrides the image CMD (leaving ENTRYPOINT intact), so the Compose snippet can be OK.
- Kubernetes `command` overrides ENTRYPOINT; to override only the CMD while keeping ENTRYPOINT, you generally want `args`.

## Fix Focus Areas
- setup/deployment/container-images.mdx[149-163]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

2. ~~Ambiguous weekly tag syntax~~ ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

The tags table mixes pure tag formats (e.g., :<release>, :latest) with
hoopdev-minimal:<release>-<YYYYMMDD>, which looks like a partial image reference and omits the
hoophq/ repository prefix used elsewhere on the same page. This ambiguity can cause users to
construct an invalid image reference when following the weekly-patched guidance.

Code

setup/deployment/container-images.mdx[R168-173]

+| Tag | Behavior | Production guidance |
+| --- | --- | --- |
+| `:<release>` | Identifies a Hoop release, such as `:1.126.3`. | Recommended baseline. Keep the gateway and agent on the same release. |
+| `:latest` | Moves whenever a new release is published. | Use for evaluation or when your deployment process intentionally tracks releases. |
+| `@sha256:<digest>` | Identifies exact image bytes. | Use when reproducibility or admission policy requires immutability. |
+| `hoopdev-minimal:<release>-<YYYYMMDD>` | Captures a weekly OS-patched minimal image. | Use when you want a dated patch snapshot; pin its digest for strict immutability. |

Relevance

●●● Strong
Likely accepted as a straightforward docs-clarity fix; aligns with past acceptance of correcting
confusing tables.
PR-#94

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Within the same page, the weekly row omits the hoophq/ repository prefix while later text
explicitly uses hoophq/hoopdev-minimal:latest, and other rows are tag-only formats.

setup/deployment/container-images.mdx[166-176]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The “Tags and update policy” table uses tag-only formats for most rows, but the weekly row uses `hoopdev-minimal:<release>-<YYYYMMDD>` (not tag-only and missing `hoophq/`).

## Issue Context
Elsewhere, the page references `hoophq/hoopdev-minimal:latest`, implying the repo prefix matters. The table should either:
- show a tag-only format like `:<release>-<YYYYMMDD>`, or
- show a complete image reference like `hoophq/hoopdev-minimal:<release>-<YYYYMMDD>`.

## Fix Focus Areas
- setup/deployment/container-images.mdx[166-176]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

3. ~~Presidio URL/port mismatch~~ ✓ Resolved 🐞 Bug ≡ Correctness

Description

The new OCR-agent section states the “standard Helm service” listens on port 3000 for
MSPRESIDIO_ANALYZER_URL, but existing Presidio/guardrails deployment docs in this repo instruct
configuring Presidio via the Envoy load balancer on port 3010. This creates conflicting guidance and
can lead operators to configure an endpoint inconsistent with the documented Presidio topology.

Code

setup/deployment/container-images.mdx[R145-148]

+- `HOOP_KEY` — the agent DSN for the gateway's gRPC endpoint
+- `HOOP_GATEWAY_URL` — the gateway HTTP/WS URL required to start the RDP agent
+- `MSPRESIDIO_ANALYZER_URL` — the Presidio analyzer URL; the standard Helm service listens on port `3000`
+

Relevance

●●● Strong
Team has accepted fixing doc port mismatches/omissions in deployment docs (ports table precedent).
PR-#94

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The new page’s statement about port 3000 conflicts with the established Presidio integration
examples elsewhere in the repo, which consistently point MSPRESIDIO_* URLs to the Envoy LB on port
3010.
setup/deployment/container-images.mdx[143-160]
setup/deployment/presidio.mdx[171-182]
setup/configuration/guardrails-configuration.mdx[259-270]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The OCR agent section documents `MSPRESIDIO_ANALYZER_URL` as pointing to a “standard Helm service” on port `3000`, which conflicts with the existing Presidio deployment and guardrails docs that use the Envoy LB endpoint on port `3010`.

## Issue Context
In this repo:
- `setup/deployment/presidio.mdx` shows Presidio analyzer/anonymizer bind `0.0.0.0:3000` internally, but the recommended integration endpoint is `http://presidio-envoy-lb:3010`.
- `setup/configuration/guardrails-configuration.mdx` uses `http://presidio-envoy-lb:3010` as the example endpoint for both analyzer/anonymizer URLs.

The new page should either (a) align with the existing guidance (Envoy LB on 3010), or (b) explicitly explain when/why direct access to `presidio-analyzer:3000` is correct and how that service is exposed.

## Fix Focus Areas
- setup/deployment/container-images.mdx[143-165]
- setup/deployment/presidio.mdx[171-182]
- setup/configuration/guardrails-configuration.mdx[259-270]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

4. ~~Undocumented HOOP_GATEWAY_URL~~ ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

The new OCR-agent section introduces HOOP_GATEWAY_URL as a required setting, but this variable is
not referenced anywhere else in the documentation (agent configuration reference or
environment-variable reference). This creates a documentation inconsistency that makes it difficult
for operators to validate the correct variable name/value.

Code

setup/deployment/container-images.mdx[R145-147]

+- `HOOP_KEY` — the agent DSN for the gateway's gRPC endpoint
+- `HOOP_GATEWAY_URL` — the gateway HTTP/WS URL required to start the RDP agent
+- `MSPRESIDIO_ANALYZER_URL` — the Presidio analyzer URL; the standard Helm service listens on port `3000`

Relevance

●●● Strong
Docs consistency gaps (missing required config/env vars) have been accepted to fix in prior reviews.
PR-#94

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
HOOP_GATEWAY_URL appears only in the newly added page, while the existing agent and gateway
environment-variable reference pages do not mention it.
setup/deployment/container-images.mdx[143-160]
concepts/agents.mdx[57-69]
setup/configuration/env-vars.mdx[6-78]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`HOOP_GATEWAY_URL` is introduced as a required env var for the OCR agent, but it is not documented anywhere else in this repo.

## Issue Context
This is a docs consistency problem: readers have no other reference for `HOOP_GATEWAY_URL` (unlike `HOOP_KEY` and `MSPRESIDIO_*`). If `HOOP_GATEWAY_URL` is correct and image-specific, it should be documented in an appropriate reference page (e.g., agent env var reference), or the OCR page should link to the authoritative reference that defines it.

## Fix Focus Areas
- setup/deployment/container-images.mdx[143-165]
- concepts/agents.mdx[57-69]
- setup/configuration/env-vars.mdx[6-78]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}

Align Presidio endpoints, document the agent gateway URL, preserve the OCR entrypoint across orchestrators, and clarify weekly tag syntax. Fixes #DEP-91 🤖 Generated with Mister Maluco Co-Authored-By: MisterMal <teskeslab@lucasteske.dev>

feraio · 2026-08-04T20:24:31Z

Looks good to me, I'd just suggest to have someone from engineering to double-check it.

docs: explain Hoop container image choices

d748a3e

Document gateway and agent image roles, safe selection criteria, Helm migration requirements, and image tag policy. Fixes #DEP-91 🤖 Generated with Mister Maluco Co-Authored-By: MisterMal <teskeslab@lucasteske.dev>

racerxdl requested review from EmanuelJr, feraio and sandromello August 4, 2026 18:07

racerxdl marked this pull request as ready for review August 4, 2026 18:08

mintlify Bot deployed to staging August 4, 2026 18:08 View deployment

qodo-code-review Bot reviewed Aug 4, 2026

View reviewed changes

Comment thread setup/deployment/container-images.mdx

Comment thread setup/deployment/container-images.mdx Outdated

Comment thread setup/deployment/container-images.mdx Outdated

Comment thread setup/deployment/container-images.mdx Outdated

fix(docs): correct image deployment guidance

aa561fd

Align Presidio endpoints, document the agent gateway URL, preserve the OCR entrypoint across orchestrators, and clarify weekly tag syntax. Fixes #DEP-91 🤖 Generated with Mister Maluco Co-Authored-By: MisterMal <teskeslab@lucasteske.dev>

mintlify Bot deployed to staging August 4, 2026 18:23 View deployment

Navigation Menu

Uh oh!

DEP-91: document Hoop container image options - #156

DEP-91: document Hoop container image options#156
racerxdl wants to merge 2 commits into
mainfrom
dep-91

racerxdl commented Aug 4, 2026 •

edited

Loading

Uh oh!

mintlify Bot commented Aug 4, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Aug 4, 2026 •

edited

Loading

Uh oh!

qodo-code-review Bot commented Aug 4, 2026

Uh oh!

qodo-code-review Bot commented Aug 4, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

feraio commented Aug 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

racerxdl commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Dependency

How to test

Setup

Steps

Link check

Uh oh!

mintlify Bot commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify Bot commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for decap-documentation ready!

Uh oh!

qodo-code-review Bot commented Aug 4, 2026

PR Summary by Qodo

Uh oh!

qodo-code-review Bot commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review by Qodo

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

feraio commented Aug 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

racerxdl commented Aug 4, 2026 •

edited

Loading

mintlify Bot commented Aug 4, 2026 •

edited

Loading

netlify Bot commented Aug 4, 2026 •

edited

Loading

qodo-code-review Bot commented Aug 4, 2026 •

edited

Loading