docs: restructure custom sandbox images into landing page with sub-pages - #840
jpshackelford wants to merge 5 commits into
Conversation
- Replace single enterprise/custom-sandbox-image.mdx with a five-page structure under enterprise/custom-sandbox-images/ - Landing page: warm runtime concept, prerequisites, choose-your-path cards - building-custom-images: Dockerfile, versioning, what to bake, private registries - multiple-images-warm-pools: full step-by-step guide (VM + Helm tabbed), inline scripts for both install types, config format, troubleshooting, API ref - single-image-admin-console: deprecated notice at top, Admin Console steps - using-custom-images: per-user selection, per-conversation API, warm claim behavior - docs.json: replace flat nav entry with group; add redirects from old URL Co-authored-by: openhands <openhands@all-hands.dev>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
Agent judgment calls — please reviewTwo decisions were made without being able to fully verify from source. Both are low-risk but worth a human eye. 1. UI cache duration in the troubleshooting tableThe troubleshooting entry for "saved a config but the dropdown does not show it" says:
The 60-second server cache is confirmed in Alternative: Use the conservative "wait a minute and reload" wording from the live doc (#776), dropping the 5-minute claim. A quick check of the frontend cache settings would resolve this either way. 2. VM Install script approachThe VM Install tab in Step 2 uses an inline script that calls The maintained script in Alternative: Use the The current choice (direct HTTPS for VM, Posted by an AI agent (OpenHands) on behalf of @jpshackelford. |
jpshackelford
left a comment
jpshackelford
left a comment
There was a problem hiding this comment.
Two nits from preview review.
- Rename 'How Warm Runtime Pools Work' to 'How Sandbox Pools Work' and introduce 'warm runtime pools' as the internal term, grounding the concept in user-facing language first - Split kubectl prerequisite by install type: VM needs kubectl once to export credentials, Helm needs it for every operation Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: openhands <openhands@all-hands.dev>
- Replace tabbed technical overview (overlay mode, ConfigMap semantics, env var names) with a plain three-step UX summary: set admin password, register images via API, users pick their environment - Remove 'Replicated' and 'Kubernetes' from tab labels throughout - Helm takeover behavior remains where it is actionable: Step 3 Co-authored-by: openhands <openhands@all-hands.dev>
- Step 3: fetch default template via script list command (API) instead of kubectl ConfigMap read — works for VM installs with no cluster access - Step 4: replace kubectl pod inspection with script list + Settings UI verification; kubectl diagnostic commands moved to troubleshooting table - Helm takeover warning stays in Step 3 where it is actionable Co-authored-by: openhands <openhands@all-hands.dev>
Docs PR OpenHands/docs#840 dropped kubectl from the sandbox-image workflow: the default template is now fetched from the Runtime API ('list' + jq) instead of the warm-runtimes-config ConfigMap, and verification is just 'list'. Mirror that here by adding 'ohe images save --from <name>', which fetches an existing configuration (typically the installer default v1_current), strips name/source, applies --image/--count, and saves — collapsing the documented list|jq|save template dance into one API-only command. --file/stdin stays as the alternative for edited bodies; exactly one of --from/--file is required. README updated to the API-only flow. Co-authored-by: openhands <openhands@all-hands.dev>
This branch was successfully deployed
2 participants
Why
The existing single-page
enterprise/custom-sandbox-image.mdx(merged in #776) had two structural problems:Broken script links. Both links to
warm-runtime-configs.shpointed toOpenHands/runtime-api, which is a private repository. Every customer following Step 2 hit a 404 on the GitHub link and a failedcurlon the raw download URL.A single page doing too much. Building images, single-image (deprecated) configuration, multi-image warm pool setup, and user-facing image selection were all crammed together. The result was a page that was hard to navigate and made it unclear which path applied to which reader.
This PR replaces it with a five-page structure:
enterprise/custom-sandbox-images/index.mdxenterprise/custom-sandbox-images/building-custom-images.mdxenterprise/custom-sandbox-images/multiple-images-warm-pools.mdxenterprise/custom-sandbox-images/single-image-admin-console.mdxenterprise/custom-sandbox-images/using-custom-images.mdxContent sources: This PR draws on both #776 (merged) and #609 (open), taking the more accurate or complete content from each based on cross-referencing the runtime-api source code, the
utils/constants.pydefaults,warm_runtimes.pyoverlay logic, and OpenHands-Cloud PRs #1181–#1183. See PR #609 comments for the full analysis.Scripts are now inlined. Because
OpenHands/runtime-apiis private, the VM Install tab embeds the full script (callshttps://runtime-api.<domain>directly, confirmed by.pr/test results on #609). The Helm tab embeds thekubectl execvariant. Both are derived from #609's tested scripts.Navigation and redirect:
docs.jsonreplaces the flatenterprise/custom-sandbox-imageentry with a nav group and adds a redirect from the old URL.Validation
utils/constants.py,warm_runtimes.py,management_fastapi.py, and OpenHands-Cloud PRs #1181, #1182, #1183.pr/test-results.mdon docs: Multiple custom sandbox images with warm runtime pools #609 used as authoritative for runtime behaviour (KOTS password generation, overlay semantics, VM ingress exposure)/enterprise/custom-sandbox-image→ landing page; old anchor deep-link → warm pools pagecustom-sandbox-image.mdxdeleted viagit rmThis PR was created by an AI agent (OpenHands) on behalf of @jpshackelford.
@jpshackelford can click here to continue refining the PR