# To dos
~- Evaluate _index pages and standardize across account + admins
category~
~- Edit weights of topics~
- Notify TSEs, other stakeholders
- TW sign off
## Summary
This PR restructures the Platform documentation into a clearer Accounts,
Security, and Subscription and billing information architecture, with
aliases so existing URLs keep working.
Work from these PRs was merged into this feature branch:
- #25957 (Security IA)
- #25960 (Accounts and Admin)
- #25981 (Subscription and billing)
### Accounts
- Moves organization, company, and admin content under Accounts.
- Splits individual-account docs into their own subsection.
- Removes the standalone Admin section; those pages now live under
Accounts.
### Security
- Publishes Security at `/security/`, matching other Platform sections.
- Groups authentication (SSO, 2FA, OIDC), access tokens, provisioning,
and roles under Security.
- Leaves Enterprise Hardened Desktop and related enterprise security
docs under Enterprise.
- Restores shipped Hardened Desktop and security FAQ URLs so they match
`main`.
### Subscription and billing
- Merges Subscription and Billing into a single Subscription and billing
section.
- Drops the extra subcategory wrappers and nests billing tasks under
Manage.
- Shortens the billing details sidebar label.
### FAQs
- Consolidates Platform FAQs onto four pages: Accounts, Security,
Subscription and billing, and Platform.
- Folds leftover general, container, and network/VM security FAQs into
Platform FAQs.
- Folds SSO enforcement FAQs into the SSO FAQ.
- Templates FAQ pages with H2 topics and H3 questions, and limits the
table of contents to H2.
### Navigation and follow-ups
- Renames the manuals sidebar group from Platform to Accounts and admin,
and updates the manuals landing heading and copy to match.
- Fixes the MSI install Settings Management link after the security path
move.
- Updates CODEOWNERS, the labeler, and in-repo links to the new paths.
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
<!--Delete sections as needed -->
## Description
Flips the Docker Scout features that reached their retirement dates from
"deprecated" to retired, and removes the topics for them.
Docs now describe only the current product — retirement dates and
history
live in the release notes and the retired products page.
https://deploy-preview-25965--docsdocker.netlify.app/scout/
## Retired features and topics updated
| Feature | Retired | Topics |
|---|---|---|
| Slack integration | Jul 30 | Deleted
`integrations/team-collaboration/` |
| Notifications | Sep 1 | Removed notification settings from
`explore/dashboard.md` |
| Amazon ECR (native) | Sep 1 | Deleted `registry/ecr.md` |
| Azure ACR (native) | Sep 1 | Deleted `registry/acr.md` |
| Policies page in Dashboard | Sep 1 | Deleted `policy/dashboard.md`,
trimmed `policy/_index.md` and `policy/local.md` |
| SonarQube integration | Sep 1 | Deleted `integrations/code-quality/` |
| GitHub SCM integration | Jul 1 | Deleted leftover
`source-code-management/` topic; migration guidance moved to
`retired.md` |
ECR and ACR are still supported through `docker scout watch` — only the
native
integrations are gone.
## New
- `integrations/registry.md` — generic registry topic covering any
OCI-compliant registry, with Artifactory as the worked example. Replaces
the
per-registry topics, including `registry/artifactory.md`.
## Also
- Release notes: kept the original deprecation announcements (links
removed),
added retirement entries for Jul 30 and Sep 1.
- `retired.md`: entries updated, aliases added for all removed topics.
- Fixed a stale claim in `build/building/best-practices.md` that Scout
raises
pull requests to update base images — that was the retired GitHub
integration. Now points to Dependabot.
## Related issues or tickets
<!-- Related issues, pull requests, or Jira tickets -->
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [ ] Technical review
- [ ] Editorial review
- [ ] Product review
Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>
The Go guide's `COPY *.go ./` only picks up files in the Dockerfile
directory. A module with `pkg/` then fails at `go build` for a reason
that looks like a missing dependency.
Left the sample Dockerfile as-is (it's a single-directory app) and
called out `COPY . .` for multi-package trees.
Fixes#14609
---------
Signed-off-by: Dean Chen <862469039@qq.com>
The sandbox get-started page mixed platform installation with the first-session walkthrough. Add a dedicated install page with both Linux installation paths, and update related links to use it.
<!--Delete sections as needed -->
## Description
Synced DHI CLI docs:
- Release notes — Added v0.0.6 and v0.0.7 to the DHI CLI release notes
page.
- Reference YAML — Synced commands (these syncs got missed a previous
release):
- customization build get
- customization build list
- customization build logs
Backstage guide — Fixed a stale customization build list example in the
dhictl CLI tab that still used the old two-argument format; updated to
`<customization-id>` with a note on how to retrieve it.
## Related issues or tickets
<!-- Related issues, pull requests, or Jira tickets -->
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [ ] Editorial review
---------
Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>
Bare relative links in collapsed guides resolved to the guides landing page.
Replace them with same-page anchors and remove one link to a deleted topic.
Co-Authored-By: Codex <noreply@openai.com>
<!--Delete sections as needed -->
## Description
<!-- Tell us what you did and why -->
## Related issues or tickets
<!-- Related issues, pull requests, or Jira tickets -->
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [ ] Technical review
- [ ] Editorial review
- [ ] Product review
Signed-off-by: aevesdocker <allie.sadler@docker.com>
## Description
Follow-up to #25338 (the guides revamp). That PR collapsed most
multi-page guide series into single pages but left ~50 guides wrapped in
a `<name>/index.md` directory structure alongside guides that are
already flat `<name>.md` files — an inconsistent mix. This PR finishes
the flattening:
- Flattens 50 folder-wrapped guides to `content/guides/<slug>.md` via
`git mv` (history preserved). These keep the same URL, since Hugo
generates the same permalink for a leaf-bundle `dir/index.md` and a flat
`dir.md`.
- Moves the last 4 guides' local per-guide image bundles
(`genai-leveraging-rag`, `genai-video-bot`, `genai-claude-code-mcp`,
`java`) into the shared `content/guides/images/` folder with
slug-prefixed filenames, matching the convention already used by most
other guides (`databases-1.webp`, `kafka-1.webp`, etc.), and rewrites
the in-body image references.
- Normalizes `genai-claude-code-mcp`'s non-standard filename
(`claude-code-mcp-guide.md`) and capitalized `Images/` folder to match
convention.
- Promotes `content/guides/frameworks/laravel/index.md` to a top-level
`content/guides/laravel.md`, since it was the only guide under
`frameworks/` and every other language/framework guide is flat.
- Adds `aliases` entries for the two URLs that actually changed
(`/guides/frameworks/laravel/` and
`/guides/genai-claude-code-mcp/claude-code-mcp-guide/`); every other
rename preserves its existing URL.
Companion PR establishing this as the documented convention going
forward: #25503
## Validation
- `hugo --minify` build via `docker compose run` completes with zero
warnings/errors (3174 pages, 1524 aliases — unchanged from before this
PR).
- Verified both changed-URL guides render at their new path and the old
path 301s via the Hugo alias redirect.
- Verified every image reference in the 4 migrated guides resolves to an
existing file in `content/guides/images/`.
- Multi-agent docs review (link-checker, cross-reference-checker,
guide-conventions) found zero issues.
## Related issues or tickets
Discussed in the team's docs Slack channel following #25338.
## Reviews
- [ ] Technical review
## What
A full revamp of the `/guides` section — taxonomy, structure, and UX.
Preview: https://deploy-preview-25338--docsdocker.netlify.app/guides/
### Taxonomy & structure
- Replaces the sprawling 24-tag set with a focused 9-tag taxonomy
aligned to use case / SDLC: **Languages & frameworks, AI, Testing,
CI/CD, Security, Databases, Deployment, Admin, Hands-on labs**.
- Removes the languages taxonomy entirely (`data/languages.yaml` and all
`languages:` front matter).
- Collapses all multi-page guide series into single pages, with aliases
so old sub-page URLs continue to resolve.
- Deletes redirect-only shim pages and flattens directory-wrapped single
pages.
### Landing page (`/guides/`)
- A clean index: hero, then category sections listing each guide as a
plain **title / summary** row.
- **Browse rail** (sticky, left): click a topic to filter the page to
just that topic's guides; "All guides" resets. A count + Clear bar
appears while filtering.
- **Text filter**: instant client-side search over title, summary, and
tags. Topic filter and text search are mutually exclusive and share the
same flat-list view.
- No more "Featured guides" section.
### Guide content pages
- Removes the left sidebar for the guides section (mobile drawer kept).
- Centered reading column (`92ch`) with the TOC taking the remaining
width.
- Summary rendered as a lead paragraph under the h1.
- TOC scrollbar auto-hides until hover; breadcrumbs render at a
consistent size inside and outside `prose`.
## Notes
- Deep full-text search across guide bodies is still handled by the
existing site-wide Pagefind (⌘K); the landing filter is the fast
metadata-narrowing surface.
- `series.html` is retained — it's still used by `get-started` pages.
## Validation
- Site builds clean locally (Hugo dev server, no errors / broken refs).
- All collapsed sub-page URLs redirect via aliases.
## Follow-ups
- Prune guides that we no longer need/want
- Tighten the guides that span too many concepts (e.g. language guides;
remove cicd/deploy/sscs)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
- Python/Ruby GitHub Actions CI guides: 'is runs' -> 'runs', 'of you' ->
'of your', and 'Login to Docker Hub' link text -> 'Log in to Docker Hub'
- configure-builder: 'of you workflow' -> 'of your workflow'
- bind-mount page: remove stray article ('the a container' -> 'the container')
- pre-seeding guide: 'let you access to' -> 'letting you access', 'define' -> 'defines'
<!--Delete sections as needed -->
## Description
Refreshed Node.js guide
- Updated all examples to DHI. DHI Community is now free so the DOI
fallback is no longer needed.
- Replaced the git clone pattern with the file scaffolding component.
- Simplified the sample app to a Node.js backend API. Added links at the
start of the guide to dedicated frontend framework guides.
- Added "Secure your Node.js image supply chain" topic to showcase DHI.
- Refreshed topic intros and related links.
https://deploy-preview-25319--docsdocker.netlify.app/guides/nodejs/
## Related issues or tickets
ENGDOCS-3319
Closes#25280
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [ ] Technical review
- [ ] Editorial review
- [ ] Product review
Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>
Three small fixes in the guides.
- `guides/localstack`: the prose says `S3_ENDPOINT_URL` is
`http://localhost:4556`, but LocalStack's edge port is `4566`, and the
guide's own `.env` block later uses `4566`.
- `guides/pgadmin`: the top-level Compose key for the pgpass file is
`configs`, not `config`. As written the compose file is invalid.
- `guides/bun/deploy`: the "Turn on Kubernetes" link has a doubled slash
(`/manuals//desktop/...`).
Signed-off-by: Emmanuel Yusufu Kimaswa <kimaswaemma36@gmail.com>
The `/docker-entrypoint-initaws.d` directory was removed in LocalStack
2.0. Updates the Compose snippet to mount the current `ready.d` init
hook directory and adds a short tip pointing to the LocalStack init
hooks reference. Also drops a stray trailing quote that made the
previous mount path invalid.
Closes#22640
<!--Delete sections as needed -->
## Description
Updated Python guide
- Removed DOI in favor of DHI only. DHI Community is now free, so
there's no reason to keep the DOI fallback path.
- Removed the git clone sample-app pattern. Maintaining external sample
repos is a burden, and split source of truth between the docs and the
sample.
- New file browser / scaffolding component. Lets users copy individual
files or scaffold the whole project with one command. Replaces the role
the cloned sample repo used to play.
- New "Secure your supply chain" topic highlighting what DHI gives you
and how to attach matching attestations to your own image in CI.
- A bunch of smaller improvements: clearer intros for each topic,
progressively updating the same app in all topics, ran and fixed issues,
etc.
https://deploy-preview-25206--docsdocker.netlify.app/guides/python/
## Related issues or tickets
ENGDOCS-3308
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [ ] Technical review
- [ ] Editorial review
---------
Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>
<!--Delete sections as needed -->
## Description
Added VEX walkthrough guide for Docker Hardened Images
The existing DHI documentation covers VEX concepts and scanner
integration, but as separate reference topics. Users who want to
understand VEX in practice have to piece together the workflow
themselves.
This guide shows the full workflow end-to-end against a real image
(`dhi.io/python:3.13`): scan without VEX to get the raw CVE baseline,
fetch the attestation, scan again with VEX applied, then inspect every
suppression and the reasoning behind it. Each step shows actual command
output so readers can compare what they see against a known reference.
The guide covers:
- Before/after scans with Trivy and Grype to make the VEX effect
concrete
- Docker Scout's automatic VEX integration as a contrast
- Trivy's `--show-suppressed` flag to surface per-CVE justification
codes
- `jq` queries against the raw VEX file to read Docker's human-readable
reasoning and filter by status (`not_affected`, `under_investigation`,
`affected`)
The goal is to give readers a working mental model of what VEX does and
how to audit it — something a walkthrough can do that reference docs
can't.
https://deploy-preview-24992--docsdocker.netlify.app/guides/dhi-vex-walkthrough/
## Related issues or tickets
ENGDOCS-3239
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [ ] Editorial review
---------
Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>
## Summary
The Node.js containerize guide told readers to create a Dockerfile
without saying where to place it. This clarifies that both Dockerfile
options belong in the project root.
Closes#25185
Generated by Codex
Co-authored-by: Codex <codex@openai.com>
The Node.js containerize guide told readers to create a Dockerfile without saying where it belongs.
Clarify that both Dockerfile options should be created in the project root and clean up existing lint failures in the touched file.
Co-Authored-By: Codex <codex@openai.com>
Two related style-conformance fixes across `content/guides/`, motivated
by a recent audit of guide-page style against STYLE.md, COMPONENTS.md,
and AGENTS.md.
## What changed
### 1. Add missing `keywords:` frontmatter to 104 guide pages
`keywords` is documented as required (AGENTS.md, COMPONENTS.md) but was
missing from 10 single-file guides, 8 `_index.md` landing pages, and 86
chapter pages. Each page now has a meaningful, page-specific
comma-separated keyword list derived from its title, lead content, and
sibling pages where applicable.
Examples of the convention applied:
-
`content/guides/testcontainers-java-spring-boot-kafka/create-project.md`
— `testcontainers, java, spring boot, kafka, mysql, project setup`
- `content/guides/docker-compose/why.md` — `docker compose,
multi-container, yaml, services, orchestration, application`
Post-change verification confirms zero guide pages under
`content/guides/` are missing the field.
### 2. Remove bold-for-emphasis from 14 guide pages
STYLE.md restricts bold to UI elements only — never for emphasis,
product names, command names, or the `**Term**: description`
subsection-label pattern. Cleaned up the top-15 offender files
identified by raw bold-span count (code blocks excluded). One file
(`jupyter.md`, 32 spans) was untouched because all spans were legitimate
UI references.
Shape of the work across 14 files:
- ~60 `**Term**: description` list items de-bolded
- ~10 identifiers/values/commands converted to backticks (e.g.
`**my-mysql**` → `` `my-mysql` ``)
- ~10 product/emphasis bolds removed
- 6 bolded link texts un-bolded
- 3 blockquote-style notes converted to `> [!NOTE]` callouts
Legitimate UI bolds (button names, menu items, field labels, tab names)
were preserved throughout. `databases.md` kept 47 of 49 spans for this
reason — only port-mapping value and container name were converted to
backticks.
## Out of scope
The audit surfaced other items not addressed here:
- Series `params` block missing on all 48 `_index.md` landing pages —
this is a "decide what's authoritative" question that warrants
discussion before code changes.
- Vale prose violations (`just`, `easily`, `we`, etc.) — concentrated in
~5 files; can land separately.
- Heading numbering convention (`## Step N:` vs `## N.` vs plain) —
undocumented; should be pinned down in STYLE.md or COMPONENTS.md before
mechanical sweeps.
## Verification
- `markdownlint` (via `scripts/lint.sh`) clean on all changed files.
- Vale not installed locally; relying on CI to validate prose.
- `git diff --stat` confirms scope: 118 unique files, all under
`content/guides/`. No vendored, layout, or generated-file changes.
<!--Delete sections as needed -->
## Description
Removing `docker init` workflow from guides. See ticket for more info.
Instead, have copy-paste codeblocks of the existing output. Added tip to
use Gordon.
## Related issues or tickets
ENGDOCS-3299
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [ ] Editorial review
---------
Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>
Replaces @material-symbols/svg-400 (5.5 MB) with heroicons (488 KB) — an
11x reduction in icon asset size. Heroicons uses a single consistent
distribution format (24px solid SVGs, fill="currentColor") eliminating
the need for the separate utils/svg.html partial, the icon-svg-stroke CSS
utility, and the dual-path resolution logic in icon.html.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
<!--Delete sections as needed -->
## Description
Tested and updated the dotnet guide.
- Add missing stage name for dhi Dockerfile
- Clean up some output
## Related issues or tickets
<!-- Related issues, pull requests, or Jira tickets -->
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [ ] Editorial review
Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>
PR to capture work:
- Update / simplify titles to match docs
- Create subcategories within org/company
- Wrestle with redirect nightmare part 2
Filing a follow up PR to create parallel structure in the `Company`
subcategory. This PR's scope is for `Organization` only.
The code snippet for Dockerfile under the "Using the official Docker
images" contains a comment which says that this Docker file uses DHI
image, which is incorrect.
<!--Delete sections as needed -->
Updated the code snippet to match the tab contents
<!-- Tell us what you did and why -->
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [ ] Technical review
- [ ] Editorial review
- [ ] Product review
<!--Delete sections as needed -->
## Description
Merged how-to/debug into troubleshoot to reduce left nav sprawl. Kept
troubleshoot at top-level to align with other manuals.
https://deploy-preview-24658--docsdocker.netlify.app/dhi/troubleshoot/
## Related issues or tickets
<!-- Related issues, pull requests, or Jira tickets -->
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [ ] Editorial review
---------
Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>
Co-authored-by: Allie Sadler <102604716+aevesdocker@users.noreply.github.com>
<!--Delete sections as needed -->
## Description
- Refreshed explore based on latest GUI. Removed steps with a direct
link. xref'd to previous sections to remove redundant steps.
- Consolidated explore and compare to minimize left nav sprawl and
because they're related use-cases.
- Renamed from "explore" to "search" in order to not conflict with the
about section that got renamed explore.
- Added in CLI commands to eventually remove the bolted-on, standalone
how-to cli topic.
- Cleaned up some fluff from the compare topic that was used to make it
feel more substantial when it was a standalone.
https://deploy-preview-24602--docsdocker.netlify.app/dhi/how-to/explore/
## Related issues or tickets
ENGDOCS-3222
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [ ] Editorial review
---------
Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>
<!--Delete sections as needed -->
## Description
Aligned file name with that on line 43, using the preferred
`compose.yaml`.
## Related issues or tickets
Closes#23860
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [ ] Editorial review
Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>
