docs(deployment): expand the deployment how-to with tested guidance#1872
Open
rohitg00 wants to merge 7 commits into
Open
docs(deployment): expand the deployment how-to with tested guidance#1872rohitg00 wants to merge 7 commits into
rohitg00 wants to merge 7 commits into
Conversation
Rewrites the deployment guide to cover a real production setup, tested end-to-end against the 0.19.4 engine (the version now on Docker Hub). - Pre-built iiidev/iii images (multi-arch, distroless, non-root UID 65532) - Deploy with Docker: generate-docker assets, config + data volumes, and what actually ships in the image (engine + config, not your app) - Build from source (cargo build --release) with arch/libc caveats - Workers and adapters: in_memory to file_based, scale-out with Redis and RabbitMQ, and the restart-tier persisted-config behavior - Hardening: bind interfaces, CORS, secrets - RBAC listener (allow/deny verified) - Reverse proxies (nginx/Caddy, subdomain and path-prefix, WS upgrade/timeouts) - Health checks (distroless has no shell; use external TCP/tcpSocket probes) - Observability: OTLP only (Prometheus removed; 9464 vestigial), with the gRPC (4317) vs HTTP (4318/v1/logs) protocol split - Deploy a multi-worker product with Compose (engine + adapters + workers), plus engine-managed micro-VM workers (need a glibc base with iii-worker plus /dev/kvm; the distroless stock image cannot host them) - Deployment checklist Mirrors the canonical docs/next/using-iii/deployment.mdx into the published docs/using-iii/deployment.mdx. The .mdx.skill.md sidecars are regenerated by the render step.
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughBoth ChangesProduction Deployment Documentation
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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 |
Contributor
skill-check — docs2 verified, 517 skipped. 2 errors across the verified workers.
Caution 2 in-scope rendered artifact(s) are out of date — sources this PR touches changed without re-rendering.
Note Additionally, 104 unrelated stale artifact(s) exist on main outside this PR's scope. Not blocking this PR; a maintainer should re-render them in a separate chore PR.
|
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
- Remove all em dashes (Terminology.EmDash); rewrite with commas, colons, parentheses, or periods. - Drop the "Built-in workers" / "Your own workers" dichotomy; describe workers by where they run instead of by class. - Rename the SDK handle in the worker snippet from `iii` to `worker`. - Replace bare "telemetry" with "observability data" for the iii-observability worker's OTel data. - Remove the anthropomorphic "lives" and the "just" hedges.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
docs/next/using-iii/deployment.mdx (1)
350-366: ⚡ Quick winAdd the strict
iii.worker.yamlvalidation workflow to this production section.This section should explicitly call out that manifest validation is strict in current engine behavior (unknown keys fail validation/start), and include the
worker::validate/worker::schemaoperational workflow so operators can preflight manifests before deploy.As per coding guidelines, “worker add validates the
iii.worker.yamlstrictly… unknown keys are rejected… validation also re-runs atstart” and “worker::validate/worker::schemaprovide dry-run/schema workflows.”🤖 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 `@docs/next/using-iii/deployment.mdx` around lines 350 - 366, The production section "Adjust the worker manifest for production" is missing critical information about strict iii.worker.yaml validation behavior. Add content that explicitly explains that manifest validation is strict and unknown keys will fail during validation and start, then include information about the worker::validate and worker::schema operational workflows that operators can use to preflight and validate manifests before deployment. This addition should clarify that validation occurs both during the dry-run workflow and at start time to help operators catch configuration errors early.Source: Coding guidelines
docs/using-iii/deployment.mdx (1)
350-366: ⚡ Quick winAdd the strict
iii.worker.yamlvalidation workflow to this production section.This section should explicitly call out that manifest validation is strict in current engine behavior (unknown keys fail validation/start), and include the
worker::validate/worker::schemaoperational workflow so operators can preflight manifests before deploy.As per coding guidelines, “worker add validates the
iii.worker.yamlstrictly… unknown keys are rejected… validation also re-runs atstart” and “worker::validate/worker::schemaprovide dry-run/schema workflows.”🤖 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 `@docs/using-iii/deployment.mdx` around lines 350 - 366, In the "Adjust the worker manifest for production" section, add content explaining that the engine performs strict validation of the iii.worker.yaml manifest, where unknown keys are rejected and validation fails at both manifest load time and worker start time. Include information about the worker::validate and worker::schema operational workflows that operators can use to preflight and validate manifests before deployment. This should be added as a new bullet point or warning section that clearly states the strict validation behavior and references these validation workflows as the recommended approach for dry-run validation before deploying workers to production.Source: Coding guidelines
🤖 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/next/using-iii/deployment.mdx`:
- Around line 97-103: The deployment documentation contains inconsistent port
numbers across multiple sections that will cause configuration errors. Review
the port table at lines 97-103 (showing ports 49134 and 49135), then check the
contradicting references at lines 563-574 and 605-610 where ports 49334 and
49335 appear instead. Determine the correct port numbers that should be used
consistently throughout the document for the SDK WebSocket/worker connections
and RBAC listener, then update all references in all three sections to use the
same port mapping uniformly.
In `@docs/using-iii/deployment.mdx`:
- Around line 97-103: The documentation contains inconsistent port mappings
across multiple sections, with RBAC listener and trusted worker-manager ports
defined differently in the port table (lines 97-103) versus the configuration
examples in later sections (563-574, 605-610). Standardize all port references
throughout the document by selecting one consistent port number for the RBAC
listener (choose between 49135 or 49335) and one for trusted worker-manager
traffic (choose between 49134 or 49334), then update all occurrences in the port
table, configuration examples, and any other references in the mentioned
sections to use the unified mapping.
---
Nitpick comments:
In `@docs/next/using-iii/deployment.mdx`:
- Around line 350-366: The production section "Adjust the worker manifest for
production" is missing critical information about strict iii.worker.yaml
validation behavior. Add content that explicitly explains that manifest
validation is strict and unknown keys will fail during validation and start,
then include information about the worker::validate and worker::schema
operational workflows that operators can use to preflight and validate manifests
before deployment. This addition should clarify that validation occurs both
during the dry-run workflow and at start time to help operators catch
configuration errors early.
In `@docs/using-iii/deployment.mdx`:
- Around line 350-366: In the "Adjust the worker manifest for production"
section, add content explaining that the engine performs strict validation of
the iii.worker.yaml manifest, where unknown keys are rejected and validation
fails at both manifest load time and worker start time. Include information
about the worker::validate and worker::schema operational workflows that
operators can use to preflight and validate manifests before deployment. This
should be added as a new bullet point or warning section that clearly states the
strict validation behavior and references these validation workflows as the
recommended approach for dry-run validation before deploying workers to
production.
🪄 Autofix (Beta)
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 UI
Review profile: CHILL
Plan: Pro
Run ID: aab5f5eb-1e6c-4f78-a611-41d79ab3e292
📒 Files selected for processing (2)
docs/next/using-iii/deployment.mdxdocs/using-iii/deployment.mdx
…aking From Linux testing: the configuration worker defaults to ./data/configuration (/app/data), not the /data volume, so it crash-loops with a permission error on the non-root image; document pointing it at the volume and the named-volume root:root caveat. Compose .env is not forwarded into the engine container, so document env_file: .env on the iii service for RABBITMQ_USER/PASS. Micro-VM baking must also carry ~/.iii/rootfs/<lang>, which dominates image size.
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Rewrites
using-iii/deploymentinto a complete production how-to, tested end-to-end against the 0.19.4 engine (the version now on Docker Hub). Edits the canonicaldocs/next/using-iii/deployment.mdxand mirrors it to the publisheddocs/using-iii/deployment.mdx.Covers:
iiidev/iiiimages (multi-arch, distroless, non-root UID 65532)generate-dockerassets, config + data volumes, and what actually ships in the image (engine + config, not your app)cargo build --release) with arch/libc caveatsin_memorytofile_based, scale-out with Redis/RabbitMQ, and the restart-tier persisted-config behaviortcpSocketprobes)9464vestigial), with the gRPC (4317) vs HTTP (4318/v1/logs) protocol splitiii-worker+/dev/kvm; the distroless stock image can't host them)Tested (0.19.4, this work)
docker compose up: engine boot, REST/WS, config + data volumesiii worker add/removehot-reloadiii-worker-- missinglibcap-ng.so.0)Not tested (documented honestly)
/dev/kvm, not available on Docker Desktop macOS -- verify on a Linux/KVM host.Notes
docs.jsonis intentionally not included (local-only tweak used to run the newermintpreview)..mdx.skill.mdsidecars are auto-generated by the render step and not hand-edited here.Test plan
http/protobufguidance against the team's collector setupSummary by CodeRabbit
config.yamlusage (read-only mounting), and durable file-based state via named volumes, including flush/durability and persisted configuration precedence after first boot.